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Introduction 


The Acorn C compiler fur the ARM processor is a full implementation of C 
&-S defined by rhe October 3 986 draft ANSI language standard- This manual 
is a reference rest designed ro accompany the Draft Proposed American 
Nunimut Standard for fn/brmati'on Systems - C” Programming Language. 
document (October 3986) and should therefore be read in conjunction with 
it. The compiler also has a Port able C compatibility mode. 

ABOUT THIS USER GUIDE 

We assume that the reader of this User Oucde has a working knowledge of 
C. The Guide does not act as an introduction to C. Subsequent chapters and 
appendices contain information On: 

* Installation and use of the compiler, in How to imiali a?,J -un the c mpiier. 

* How Acorn C implements those aspects of the language which ANSI Leaves 
to the discretion ot the implementor in Jmplemerttatkm detaih, 

* How Acorn C behaves in those ircm covered by Appendix A.fc or the draft 
standard, in Standard ImpLjmgnrutjun defiiucion. 

* The additional libraries ior the Arthur operating system and the Window 
Manager (Wimp), in Arthur operating system library, 

* How to handle procedure entry and exit in assembly language, so you can 
write programs which interface elegantly with rhe code produced by the C 
compiler in Assembly language inrer/ace, 

* Messages produced bv ihe compiler, 't varying degrees ot seriousness, in 
Errors attd tuorningj. 

* Using rhe compiler in its Potable C Compiler compatibility m"je. in 
Us mg the PCC mode, 


Calling other applications from C In a manner which allows control to 
return ro the C program, m Culling applications from C, 




If you tuasd rtfiiormalien of u more introductory’ nature, you could refer 10 the 
following bookii 

* The C. pro^rtcmjnni.e bHiftMjeji. 1 by BW Kcmighaii and DM Ritchie, 
published by Prentice-Hall, Englewood Oiffc, NJ, USA This i- rbr original 
C L bible', still useful for 3 description of FCC'Style C, hut superseded in 
other respects bs Harbison and Steele. 

* A C Referenct Manual, 2nd edition by ^.niuiel 3’ Harbison and Guy L 
Steele Jr, published by [Verttice*Hcill, Englewood Cliffs, NJ, USA. This is □ 
\try t htrough refvwnct, guide to C, including .1 useful amount ol information 
on rbe proposed ANSI draft 1 .\ 

* C Language by bnedman Vi agner-JA 1 let . pul lohvd by Ihiman, 128 Long 
Acre, London UK. 

* C, ,Piit;lr f?ix>lc b\ Al,m R Fewer. published by Prentice-Hall, Engle wood 
Cliffs. NJ. USA. 

* The XfOPEN P'TTtiabiiiri Guide, published by Elsevier Science Publisher 
BV, 1000 B Z, Amsterdam, Netherlands, 

CONVENTIONS USED 

niroughriul lhi> User Guide, the following convention is used tor test that 
appears on the screen, for L key words, macro ? library routines etc. A 
typewriter style font is used for test to he typed is is. and italic:- are used 
m denote classes of item which would be replaced in the command <r 
menage hv actual objects of the appropriate type. For example; 

cc opiums, fihmamet 

means that you type i- shown, 3nd replace Lipfions and filenames by 
specific examples. 
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This section describes, first, how to install tihe C compiler, second, the 
naming conventions used by Atom C. and firitiUv, how to mn tin: compiler 
ami control variola aspects nl ie~s operation 


INSTALLATION 


The diagram below shows rhe director, structure of the C distribution, disc 
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Upon receiving your J be, you should make a working copy and keep the 
original in .! safe ptace- To make the copy, enter the following command 

^backup Q Q q 

The program will prompt you io insert a destination disc tie a blank 
formatted BOOk disc) in place o( the original disc that you wish ro copy. The 
Arcfitmedes L-jct Guide tells you how to format ll floppy disc. 

The programs ms tall HD and tnstaLlNET arc provided on the floppy disc to 
enable you to install C on a hard disc and Econct network respectively. 
These can be run by clicking the appropriate icon from th e de sk lop, or from 
the Arthur Hr prompt by Typing 

*installHP 

or 

MnstsIINET 

as appropriate, fl you have an Econet file server, you will need to log on 
with system privileges in order to copy files into the library, Jr is 
recommended rhar you copy the structure provided on the disc supplied, 
except char directories , and r will be created at user level, Remember 
ro *er file attribute* for global use. 

Bctore running the compiler, you should ensufc that rht floating point 
emulator is installed. To do this on Anhui 1.2, you must load rhe emulator 
imm the C disc- If you are not sure what version of Arthur you are using, 
perform the following -teps to find out; 

* quit the desktop 

* from the ■ prompt, type 

*fx 0 

A message of the form 
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Arthur 1.20 <01 September 198 - r > (Error number iF' f ) 
will be displayed. II" the version number is ! 20, insert the C disc and type 
5 .lib*.fpe 

This installs rhe floating point emulator. 

GETTING STARTED 


Having hacked up the C distribution disc, insert your working disc in the 
drive .uid select the directory $ .ARM.BENCH by entering the following at 
the * prompt: 


* DIR $.ARM.BENCH 


There arc four example pn grains provided on the disc (see the dircetorv 
structure diagram above)' 


a Balls-64 

* He1low 

* HowToCali 

* Sieve 


colourful graphics demonstration 
simple test program 

see the section entitled Calling Applications /tom C 
standard test program 


To compile and link the program HellcW, type 


*cc c.heiiow 


(note that upper and lower case letters are tnretchangciihle in the 
filename), 

When this prodcs.*. h completed, the J prompt will return under \ hnishing 
message diiplavtd on die screen To run the program,, now type 


^hellow 




and the program will print the menage Hel la World un the screen. 

BaLta64 make* use l»e auntie nl the graphics taciliiies ot your Archimedes 
personal workstation. inJ need? linking with the Arthur library after 
compilation- The compiler will dr:, this tor you if you type 

*cc -Arthur balls64 

and then nun the program by typing 

"bad 1964 

Tress the f« 1 kev to leave this proemm 

The cc command and its associ ated cniivettliinn*. such as where the C 
compiler evpei ' • t ■ :ir. % ■ e i i :.ir ,, ■■ icci and imatte files, >s covered 

m detail in the sections which follow. 


NAMING CONVENTIONS 

The Atom C system, in common wirh many other t systems, uses naming 
conventions to identify ihe r.,mr classes of rile involved tn the compilation 
and linking process Many systems use conventional suffixes lor this For 
example, the suffix . c denotes (_ s un.• files on UNIX™ and M^-POS ,1H 
svstcmi. This convention dashes with \com’s use i the peruM character {« 1 
in pathname* h is more- natural under Acorn tiling systems ro use a prefix 
mechanism, eg c, f: where c Is the directory containing i. source files, and 
foe is the ftlenaine. 

However, piTnihility is in increasingly important i>sue in the C world. To 
this end. the n m < system recognises the '.standard' lile naming 
conventions and performt the appr. ipnate Transformations to const hjct valid 
Arthur pathnames Tlie i ■ iwing sections summarise ihe conventions for 
referring in source, ant lade, object and program files. 
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Source tile* 

Source tiles will be looked for in. subdirectory c. To uiJ portability, a tile 
£00. will be louked tot in £ ( c, f - i, where (? means the current 
directory. 

I Delude file* 

The way in which the compiler deals with I nc Ik Jed files depend* on 
whether the numr of the filename in rhe * . yie directive Ls between 

angled brackets < > or double quomiii.m imirU H ", The former case 

implies that rbc file is a System' tme 1 the Litrei chat it is .1 ’user 1 file 
Simply pul, system include tiles are searched t, 1 within the Compiler's 
built-in filing system, and rhen in the 'system in-Jude path This 0 rend 
from the environment variable C$L±br .v.t if possible., otherwise n defaults 
to :darr-, :1 l£, L : *cr include Alia - that i*. those enclosed in double 
quotation mark- - ate -.ought in the current directory, rhen the system Include 
park 

In hot 1 1 cases .in 1 nr ei mediate ut >! u; tt search may be specified 

using the -1 command'line flag. Much more mform.tr ion about Include file 
processing may be found in rhe section on the - - -inJ - ihp below 


Object fil es 

The object files created hy the compiler arc '.to red ir, rhe Jireciorv within 
the currently selected direcmry Hiui the result of compiling .e>:rr wall 
be found in o „ &xp; 

Compilation list files 


If rhe - list keyword is 'pccrfu-%1, then a file con tin nine a compiliinnii 
listing for each compiled source file is created in the directory '■ - Thus 
compiling the file c .eur with rhe keyword - licit will result in the list 
file {?. 1. expr being created. 



Library files 


The default link step activated by the compiler searches for libraries in ibe 
'system library path' Ah With thr system include path, the compiler trie* to 
read the system library path from iHe environment variable CS lib root. If 
this isn't defined, die- path 5 + a£nu clib is used instead. In either case, . o . 
is appended rn the directory name, 

SrandarJ library hies are called a r. i i _ i t<, Art r. arLib and SuperLib. 
These contain the code for the ANSI library, the Arthur^pcdfic, library and 
the SpringBoard/Braiil library respectively The command line flag - 1 may 
S’l- u^ed to override this search path with 'tie or more user-specitiej ones. 

Program files 

Tlie result i linking the compiled versions of the source files given in the 
command hne r: the iibraiSL 1 - e an executable program hie. This is 
named 

-.fildL where file! is the name of the firor source file given m the command 
line This convention may he overridden by use of the - Hag. 

As an example of these naming conventions in use, consider the directory 
Dench on the distribution disc; 

The directory bench . c contain? C program sources 

Bench, e.sieve is the "Oarer ot a nampk program which compute-- prime 
numbers b\ the sieve of Eratosthenes. It would be referred in in a command 
Itate sis sleve, c or c .sieve, 

ThL- compiles to produce the object file bonch t Q .sieve 
This obiei .1 rale is linked with the standard library to produce the 
executable program bench, sieve 

The compiler does not check whether the filenames you give are acceptable, 
ic contain only valid characters and arc ol acceptable length - this is done 
by the filing system. 
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COMPILING A SIMPLE PROGRAM 

The compiler can only He used from the ■ prompt It you .ire using the 
desktop, tecum to the ' prompt hy clicking the select button on (he F?crt Icon- 
Nest,, load the floating point emulator hy Typing 

rjriload S „ library * fpe 

You are now ready to run the C compiler, 

The compiler is called cc, To run it, type; 

* cc options /tlenmnej 

The apporcs .ire described in detail below, They allow you lo control the 
compilation !K for eximple, oveHiding default names. Often, just the list 
of one or more filenames i:> all that is required following the cc command. 
For example, suppose you have treated the following program? 

#include- <3tdio-h> 
int main() 

I 

print! ("Hello world! -, n "*) ( 
return 0; 

I 

,ind stored ii as c,hej 1 To compile it, you entei the command 

*cc hello 

Assuming that everything is correct, the compiler will give you u message 
similar to the following: 

Norcroft APM C (with debugger support) 1.65A May 20 
1300 



Tltis compilation produces the object file o - hel ’. o. The compiler 
iiutomiiitically Issues rhe Link command necessary ro combine the object file 
with rhe standard libraries in order to produce the executable tile called 
hello. This can be executed using the command *hell a. 

You can suppress the linking stage by specifying a command line option 
This, and other options, dte described in rhe Miction below 

COMPILER OPTIONS 

You c.m control many aspecis of the compiler’s operation hy appending 
options to the command cc All options are prefixed hy the minus sign - 

Options come in two terms. The ItfM arc keyword* These ,ifc mulnple- 
characteT options and ruhttol Acorn e AidLuf-apecifk aspects of the 
compiler Keywords .tie recognised in upper or lower case. The second form 
of option is [he flag- A [lag a single letter. The case of the letter is 
usually unimportant m the C compiler under discussion However, UNIX 
compilers only tec lynl-H.' one hum it it her the upper <<t lower l.,-lsc one, 
depending on the (lagl ,ind this one should he used in preference 

The question of rhe case of flags is mosi important when you arc cunsiJering 
porting 'make' flic* to Other systems, hi using the ‘universal" syntax of the 
oc command* you can move vour system to different environments with the 
minimum amount oi work 

The keyword option* are: 

Give a description of the compiler’s command syntax - 
-in AJJ rite Arthur interface- library to the list of'standard 1 

libraries passed h the linker. Fhis is only valid under rhe Arthur 
operating system 

-super Add the Braid supervisor interface library to the list nf 

‘standard 1 libraries parsed to the linker. This is only valid under 
Braid, Spring Board and Arthur. II rhe -Att.ruj: keyword is also 
given under Arthur, then thin takes priority. 
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-pc.:- Compile oltLsryle ponabk C compiler' C This, is often 

reierred to as Kemighan and Ritchie Cn^r just K iy Rl U Thi? 
changes the syntax that is acceptable to the compile^ hut the 
default header and library files are still used. See the section on 
this option for more details. 

-list Create a listing file. Tho consists of lines of source interleaved 
with crfOt and warning messages Finer control over the contents 
of this file may he obtained using the -f Hug; (see below). 

The flag options are I bled below-. Some of these .we followed by an 
argument Whenever this is the ease. the compiler allows whireapnee to lie 
inserted between the flag letter and the argument However., thi> is not 
aiway: true of other C compilers, ?a the -.yrirax given lists only the form that 
would hr acceptable to a UNIX C compiler. Similarly, unh the case ot the 
letter that would he accepted by a UNIX C compiler ii shown, 

The descriptions ire divided inn* several sections so that Hags controlUng 
related aspects .'f the c- mpilcr - operation arc grouped together. 

Controlling the linker 

-c Do not perform the Link step. This merely compile* (he source 

program($), leaving the object ft Ms ) in the o directory, 

NB This is different horn the -C option described below. 

-I fibi This specifies a list of libraries which will he used in the Link 

command, issued by the compiler. The Usr of libraries to be used 
follows the flap (.with -pin rial white-space between the flag and 
the list!, and uh‘-- comma.* n *ep.irate items in the list. 
Alternatively, multiple - L flags may be used to specify more 
than uric library. Note that the libraries given by tho option are 
used insti'dif i }f rhe standard ones, not in addition to them. 

This flag is not compatible with corresponding UNIX t = 
compiler option, which has no direct equivalent under Arthur. 




Controlling the prc-processor 

The - I and - i control the search paths iji-t'd when the compile i is 

looking for Included files* Before describimi chew flag*., we explain the 
way in which the search paths are used. 

Use list of paths comprises three separate elements. Jn order, these an: the 
directory containing the current source file, am directories given hv - I Hags 
{in the order they appear on the command line', and finally the ‘system 
include path' In the absent* of any - j flag on the command line, the system 
include path is read from, the string variable S 'I it: ot. In the absence of 
that variable, 5 , airjtw cl ib is used, 

When a directive of the form 

#include <Tiiena/ne> 

or 

iinclude * filename" 

is encountert:d T the compiler behaves as follow*. 

H fil is a 4 rooted filename, that is 

* an Arthur filename beginning with a 5 .ir an i 

* a UNIX filename beginning with a / 

■ jn MS-DOS filename beginning with ,] \ 

then ji is used is written (except that UNlX^style and MS-DOS-style 
filenames are first tranri ited to equivalent Arthur filenames as described 
below). 

If filename is not J rowed’ tn rhe wn.se described above, then the compiler 
looks for it in a sequence or places {directories) called the search fwdi, The 
search path is in three parts, in order:: 
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the compiler's own in-memory tiling sysrem; 

the directory containing the source file (C source or ff i nc I uoed header) 
currently being processed by the compiler (rhe ‘current place")? 
the remainder of the path, formed bv connate nattily rhe lists ■. directories 
given as command line arguments to - I flags with the system search path 
(see below} The system search path is searched last. 

It the # inc.u-cod filename is given tn .ingle brackets < and >, then the 
directory containing the current source file ts nor searched. 

if the ft included filename ls given in double quotation marks then the 
■compiler's in-memory tiling system is not searched 

In Kith cases, to facilitate the porting of code from UNIX and MS-DOS to 
Arthur, U'NIX'STyltr .irnl MS-IXIS-sfyle fdcnsimes ate translated no 
equivalent Arrhut-style filenames. For example: 


. . ' i n c 1 u dfj de c £ . h 
. . \clx. hash . h, 

1ncl.udes*h 

hut 

system,defs 


is translated to 
is translated to 
is translated to 


is trn ns luted to 


■ . include«h, de. f s 
’ . clx. h. hash 
r.. includes 


systsm.defs 


(Similarly, she lists of directory names given i=. irttumcnt- ro rhe compiler s 
-I and - j comm ami-line rlags |see below) are translated to Arthur format 
before being used}. 


When Hie > found relative u an dement of the search path, the name ■■! 
rlie Jiretion, contaming that file become* rhe new 'current place' When rhe 
compiler has brushed pioce^tng that file Li restores the old current place. 
So, at any given instant. there is .l srack of current places corresponding to 
rhe stack of nested it include* 


Fur example* -.uppose the current place is Z . include and that the 
compiler is seeking the * in cl udc-J tile "ay a . ief . h r< (. <t 




"aya . h. def s ", "sy a f tie£s . h", ere). Now suppose tht^ is found in 
5 . include - sys „ h . def s- Then the new current place becomes 
$. include. 97 $ and files # 3 ncladed hy r.. def 3 , wliase names are nor 
rooted, will be sought relative to $ * Include. sy& 

In all this, the penultimate . e and . h components of the path art: omit red. 
These are logically pan of the filename - a filename extension - not 
logically part of the directory structure However, directory names other 
Than c, n, O Lind a are not so recognised (.as filename extensions' and are 
nied ‘as is'. For example, the name £ y s - new . de £ e ls exact b, that: it is not 
translated to sys , def s . nett and* if it is found, the new part of the name 
does become parr of the new current path 

Initially rhe system path is 

the path given as an argument to the -i tiimmanddine flag (see below); r>r 
the value of the system variable . i nroot, if this is set and (here is no - - 
flag-, athrmne, 

? „ arm.el 4-b 

In the first case, rhe in-memory filing system o omitted Horn thv froni of rhe 
pach searched for # i ncl jde </ilt?uuw - it l in I'r reinstated b* using the 
pseudo filename ; r em as an argument to a - I (lag or the - ; (lag. If ; mam 
is included in the search path in ihfc way, il=- position in the path is as 
specified, nor necessarily first so you can rake complete control over where 
rhe compiler seeks ^included files. 


-Ipjib Th]^ .iddt the specified directory to rite list of places which ;ife 
searched for include files (after the itvmetnory nr source file 
directory* according to the type of include file), The directories 
arc searched in the order in which they are given in — I options. 
The path should end with rhe name of a directory,, with no , h*, 
which is added automatically, 

- j diTi This overrides the system include path with the list erf directories 
which follows the flag. Hie directories are separated by commas. 
You, can specify the memory fib system in the list by using rhe 
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name :mem (in any easel An example is 
myhdr 3 , iineaii 3 .prc j ,public T hdrs. 

-j is an Arthur-specific iW r and therefore non-portable. 

-E If this flag is specified, only the pre-processor phase ot the 

compiler is eneeuted. The output from the pnvprocessor is sent to 
the standard output stream, It can he redirected to a hie using 
the usual methods. By default, comments are stripped from the 
output, but sec the nest ting. 

-C This is used in conjunction with -E above. It re instates comments, 

so they appear in the output produced hv the pre-processor, Note 
that it is different from the -q flag, which t; used to suppress the 
link operation. 

-zrnod This flag can he used 1 ■» emulate £ pragma directives. The mod 
which follow? it is the snw sequence of characters that would 
follow the directive. See the section pragma Directives for 
detail*. 

Controlling code generation 

Tine options described in rbis section control tn some way the production of 

code by the compiEet- 

- qmods This flag is used to -.pecify chut debugging tables for use by the 
Arthur Symbolic Debugger should be generated, Ir is followed 
In an optional >xt - t letters which specify’ the level of 
information required, N" modifiers means 'generate all the 
information possible'. However, the tables can occupy large 
amount- >1 memory so it is sometimes useful to limit what is 
included as faElowt: 

-gt Generate information on functions and top-level variables 

(outside functions) only. 

-gi Generate information describing each line in the tile, 



4 Generate information describing all %'jrlabLes. 

The muditiers may be specified in unv combination, eg -qiv. 

c file This flag specifics the name of .1 file in which the output of the 
linker should h stored, b overrides Hie default, which is to use 
the same name as the root name of the fttsc source file mentioned 
on the command tine* 

l Tli3s flag causes The compiler ro generate code which allows 

"profiling 1 of the program to cake place The profit ins 
information may be printed out by calling the function 
_rnapEtore () just before the program terminate?'. 

When this option is given, the compiler embeds calls m a 'count' 
routine at the start r each function body. Whenever it is called, 
the routine increment- a 32-bit counter associated with the caller. 
The _!T<apS! : s • ■ function prims the values or these counters, 
along with their associated addresses, It also prints the addresses 
nr all of the programs function entry points, so that vnu can 
deduce how often each function {or pan thereof) was called 
Note though that this doesn't tell you how long the program spenr 
in a routine, only how often u was there {hut, usually, these are 
related values). 

3 If this flag is specified, no object code is generated and, 

naturally, no attempt is- make to link it, Instead, an assembly 
listing nr the code produced is written rn a file called s „ fi le, 
where ■' is The name nr rhe source hie 1 stripped of any 
direcrones or suffixes) 

Dsym Define as a pre-processor macro, as if by a tine 
ft define sym 1 


at 1 he head of the source file 
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-L'syrn Un define s\m, an if by u line 
It undef svm 

.ii [hu head hi the: source file This may be used to cancel the 
effect .ii otherwise predefined symbol*, eg ARM. (A macro ark 
is predefined N and ha> the value 1.). 

Controlling warning menage* 

The -w option controls the suppression of warning messages. Usually the 
compiler is very free with it" warning, as this tends to indicate potential 
portability or other problems- Howe vet. t ■■ m.m\ such m-^.ige- cun he .1 
nuisance in the early stages of developing a program. - > they may he 
dbablcd- 

- Wiripd If no modifier letters mod are given, then all warnings arc 


suppressed. It one or more letters follow the El, jet. then only the 
class of warning * controlled by those letter? .ire suppressed- The 
lettcfs are: 


a 


Give no Use of = in a condition cm text warning. This 
is given when the compiler encounters statements such as 


if (a^b) j 


where it is quite possible that == was intended. 


c 


Give no <cp > implicit cast of pointer to rron- 
equj. . . r:r --r naming. Pointer casts should always be made 
explicit using irype * i operators, except in the case of HULL, 
which is a universal pointer. 


0 


Give no Unused static definition warning-If an object 
was defined to be static and was not referenced in the same file, 
in can perform no useful Junction and is therefore redundant- 




n Give na Implicit, nariawing cast w^ing. This warning is 

issued when the compiler detects an .assignment of an expression 
to an obj*ci of narrower Width (eg nt to short ). This can 
cause problems with loss of precision for certain vatues. 

p Allow characters after #else and #end±f directives Normally 

such characters are not allowed and their presence could signify 
trouble. 

S Give no Short is slower than int on this machine 

warning. The statement is true, but there's a limii to the number 
of times you have to be told... 

v Give no Imp! 1 cit reiarr. in non-void context 

warning. This is must otien caused by a return from a function 
which was assumed tu return ir-i (because no other type was 
specified) but is in fact being used as a void function, 

z Give no Array [0] found error., 


Ccmtrolling additional compiler features 

The -f flag described m this section controls a variety of Compiler features, 
mcludinp certain checks more rigorous than usual Like the previous flag it is 
followed by modifier letters. At least one letter i' required. 

a Check for certain types of ctara flow anomalies. The compiler 

performs da&i flow analysis as- part of code generation. The 
checks enabled by this option can sometimes indicate when an 
automAtiC variable has been used before it has been been 
assigned a value. 

s Check that external names used within the file are still unique 

when reduced to six case-insensitive characters. Some linkers only 
provide six significant characters in their symbol Tables This can 
cause problems with clashes it a system use>, two names such as- 
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getExprl and getExpri, which are univ unique in the eighth 
character. Note that the cheek can only he made within one 
compilation unit (source hie) so cannot catch all such piohlems 
(Note alsML> that the system under discussion allow; external 
names of up to 256 character?, su this is realty 3 portability aid-) 

f Do not embed function names in the code area. The compiler 

Joes this to make the output produced by the stas k hicktruce 
function (which is the default signal handler) and _ mapsr, o : * O 
more readable Removing the name?. from the compiler makes 
the code slightly smaller uvpu .iltv 5%) at ihe expense of less 
meMittngful hjckincCH and “.at r i i outputs. 

h Check that all exrernal objects ate declared in some included 

header file, and thar all static objects are used within the 
compilation unit in which they are defined These checks support 
good modular programming practices. 

i In the listing file (see -] ; at1 include the lines from any files 

included with directives or the tewrn: 

#Include "file” 

As above, but for files included by lines of the form: 

#include 

it Give a Wriming tor pre-processor symbols rhn ate defined hut 

not used during the compilation, 

i. Report on explicit casts of integers into pointers, eg 

char 'gc - (char *) anInteger; 

Implicit casts are repotted anyway, unless suppressed by the - 
wc option, 



u By default, the source text a.s "seen" by the compiler alter 

preprocessing {expansion) is listed, If - tu is specified then the 
wneKfmTVLkd source text, as written hy the user, i« listed. 

Consider the line 

p « NULL; 

By default, this will he listed as p= i Q J ;, with - f u specified, as 
p=^NULL;. 

When writing high-quality production software, you are encouraged to use at 
least, the -fah options in the later stages of pro-pram dnopment '-the extra 
diagnostics produced can be annoying in the earlier stages). 

COMPILING AND LINKING 

As alttMdv shown, to i-unpile and link the simple program shown above you 
would type: 

cc hello 

This produce;- the executable program hello To produce j program with a 
different name. vou would use the -c option, ec: 

cc -o greeting - hello.c 

This time the linker would produce a program that you could run using the 

co mma nd greeting* 

When writing pro-pirns that uw several source files, you may want to 
compile them selective!’, and perform the link as u separate step. For 
example, if a program consists of the files el , c a e2 , c and $3 . c. and you 
h ivc just edited o_ . :, you may want ro compile this, then Imlc the object 
file with the two other files i 

cc *~c e2 . c 

link -o sxpr o.el o.e2 o.e3 -lib 5,arm.clib + o + ^nsilib 
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Alternatively, 

cc -o expr el .a e2,c e3.o 
does the trick! 

See the linker documentation for man- details an linking- Fo maintain 
complex, rmilliEUe programs. consider ufrftg a ‘n'nke’ utility such as AMU, 
which farms pari at the Software DeveloperV Toolbox. 

Tu compile several different source program- and link them all together 
into one executable file, list all the filenames separated by spaces The 
name of rhe executable program is taken from the first filename given 
unless -d rrogna/ne is used- 

For example, the command: 

CC rcialnprcqr util extra 

compiles the sources c , :ria a n p r : -a, t. ut: . md , e :•: 1 : > into the object 
files o.ma inprog, 3 . ut i 1 and cue*' ?a, and then links all three object 
files together with (he standard library to produce the executable program 
mainpirog. 

ttpragtma DIRECTIVES 

The ANSI standard specifies a prc-pnAeSA'if directive Ipeagma, which 
provides an implementation-specific means of controlling the behaviour of 
the compiler, 

The following #pCrioma directives are recognised by the compiler in lower 
or upper case. In each case n must be either I (to enable the feature) or 0 
(to disable it}. 




# pragma. -an 

This directive is used, ro enable and disable The generation of code which 
cheeks for Slack overflow. If n IS I, stack checking cod? will he generated; 
tKis is the default action Jt tt is ■, no staclochecking code will he generated 
[t r, is hot present. rhe stack checkim* stare is restored to its default, le is 
enabled. 

You should rarely need to use this option The wldifum of k checking 
c( dc ro a function only odds (generally!! Two instruction* and Two cycles 
(less than lYiiiJsi to the exeeurimi time of a function m the case of no 
overflow. 

One occasion when it would he u-ed i- in writing a signal handler for the 
SluSTAK event. When rhis occurs, stack overflow has already been 
detected, so checking for it Tgatn m the handler would result in a fatal 
circular recursion 



MPLEMENTATION DETAILS 


This chapter give* del ail* nf those aspects •! the compiler which The Jr,nit 
AN?] sundard identifies ay mipiemensaEitm Refined, and some ■ piiws 
i't inteiest n» programmer'. They .ire grouped here hy subject! secium HI Lifts 
lhe pmt li’ i r l-l|ui ted eli be JoeLiinenred ax j -l'i u-ut jn appendix A 6 .it the draft 
siiiiidtirJ. 


IDENTIFIERS 


Identifiers can be of any length They art* truncated by the compiler to 
characters, all of which are -ii^mhcant ithc standard requires a minimum of 

31). 

Hie -.ourtc character set is determined by the host operating h>iceii Lpper 
and tower case characters are distinct in all tdemilier*. both cinema I and 
external 

DATA ELEMENTS 


The site* of data elemenio ate as ml tows 


Type 


Sire in bits 


char 

short 

int 

long 

float 

double 

long double 

all pointers 


8 

16 

32 

32 

32 

M 

n4 l subject to fun ire change) 

32 


Integer-* are represented in two'* complement form. 

Dam items of type -har arc _nsi inea bv detank, though she-, may be 
explicit) V declared as si rrve-d jn&r or uns r gr^d char. Single •character 
constant* are rhm always positive. 




Floating point quanti[its arc stored in the IEEE format. In double and long 
double quantities, the word containing the ngn, the exponent dnd the moat 
Significant purr of the mantissa i- stored at the lower machine address 

Limit*; h . float and h . limits 

Tlie standard define'’ two headers, h„limits and float, which contain 
constant declaration* Je'itnbittg the ranges of values which can hr 
represented by the ariihmetk types. The standard also defines rtummutn 
values for finny • »i these constants 

Tift- following table sets our the values in these rw. headers on rht ARM, 
Htid .i brief description of their signifiicante. See rhe draft standard for a 
full definition of their meanings. 

Number of hirs in smallest . hjeer that i* not a hit field (ie u byre); 

CKAR_BIT 8 

Numeric tange* ,ji integer typer.: The column on the left gives the numerical 
values. The column on rhe right gives the bit patterns un hexadecimal! that 
would be interpreted as these value* in C Note though that when entering 
Constants you must be careful about the >i:e and signed-no' of the quantity 
Furthermore, constant* are interpreted differently in decimal and 
hexadecima(/octal- See the ANSI standard i.u Hurbijun .mJ Sleek for 
more details. 


CHAR_MAX 

2 55 

Oxff 

CKARJHIW 

0 

0x00 

schar_max 

127 

0x7f 

5CH&RJ4XN 

-128 

0x80 

UCHAR MAX 

255 

Oxff 

shrtmaj: 

35767 

0x7 fff 

BURT MIN 

‘35763 

0x8000 




USHRT_MAX 

IN r T_MAX 

INT_MIN 

U1NT_MAX 

LQNG_MAX 

lohg”min 

ULONG MAX 

Chamcristics 

F1T_RA0IX 
FLT ROUNDS 


65535 

214746364 ? 

-2147483648 

4294967295 

2147403647 

-2147403649 

4294967295 


Oxffff 

0 x 7 fffffff 
0x60000000 

Oxltrfttft 

0x7fffffff 
QxBOOQOGOQ 
Oxffffffff 


..ij floating point: 

2 

1 


Ranges ol floating tvpes: 


FLT_MAX 3*40202341*+38F 

DBL_MAZ 1,797693134S623l57le+3Q3 

LDBL MAX 1 * 7 57 £ 33134 5 623151Le-3C 9 


FLT_KIN 1*175494356-336 

DBLJ4IN 2 * 22507 335850720138e<~3Q& 

LDBL MIN 2.225Q7385850720138e-3Q J 


Ranges of base two exponents: 


FLT_MAX_£ X P 126 
D8L_MmTeXP 1024 
LDBL_MAX_EXF 1024 

FLT_MIN_EXP (-125) 
DBL_M1N_EXF (-1021) 
LDBL MIN EXP (-1021) 


Ranges of base ten tTtronents: 




FLT MAX_1G_EXP 39 

DSL_MAX_lt>_EXP 309 

LDBL_MAX_iO_eXP 309 

FLT_MIN_iQ_EXP {-37 ] 
DB L_MXN_10_EXP [-3071 
LDBL MIN 10 EXP [-30'?) 


Decimal digits o( precufitrtn: 


€ 

IS 

15 

Digits tha.se two) in mantissa; 

FLT MANT_DIS 24 

DBL_MANT_DIG 53 

LDBL _MAIi T_D IG 53 

Smallest punitive value* *uch that (1.0 * s != 6.0): 

FLT_EPSILON 1.192O92t0e-7F 

DHL EPSILON 2 * 220446049250313le*I6 

LDBLEPSILON 2.22 0 4 4 6 0 4 92 5 0 $L 31*-16L 

STRUCTURED DATA TYPES 


FLT_DIG 
DBL DIG 
LDBL DEO 


The draft ’■[andiird leaves details of the layout nf the components nt 
structufe l£ data types up to each implementation. The following points 
apply to rhe Acorn C compiler; 

* Structures ate aligned on word houndrtlifcs. 

1 Structures are itranj-vd with the hw named component at the lowest 
addrtttjn 
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* :"ha r components art- placed in adjacent bytes, 

* shcrt components are aliened at cvcrViiddFcssev] byte*u 

« All other arithmetic type components -ire word-aligned, as are pointers and 
ints containing bitfields. 

* The only valid type for bitfields is i m, either signed or unsigned- 

* A hirtLelJ of type int is treated as unsigned by dcf&ult- 

* Bitfields must be contained within the }2 bits of an i u:.. 

■ Bitfields are allocated withm inns so that the tit?x field specified occupies 
the least significant bits of the word. 

The following point* apply to pointer types: 

* Adjacent bytes have addresses which- differ by one 

* The macro NULL expands to the value C\ with a pointer tvpe, 

* Casting between integers and pointers results in no change of representation. 

* The compiler faults casts between pointers to functions and pointers (m data, 
Fointer subtraction 

When ruo pointers are subtracted, the difference is obtained as if by the 
expression; 

((int}a - (int) b) urtt I sizeof (lype pointed tol 

if the pointers point to objects whose size is no greater than four byKS r word 
alignment of data ensures that the division will be exact in all cases. For 
longer types, such as doubles and structures, the division mas nor he exact 



unless hurh pointers are to dements of the same array. Moreover the 
quotient mav be rtxirufcd up m down ai different rimes. Heading to potential 
inconsistent ies. 


ARITHMHTIC OPERATIONS 

The compiler performs dll oi the 'usual arithmetic conversions 1 set out in the 
draft standard- 

The following points jpph to operations on the integral type*- 

* All lyned integer arithmetic use 1 ? a two’s complement represent at Eon. 

* Bitwise operations on signed integral types follow the rules which arise 
nature I ty ftom two's complement representation, 

* Right shifts Lin signed quantities arc ,arithmetic. 

* Any quantiry which specifies the amount of a shift h treated a& an unsigned 
8-bit value, 

* Any value to he shifted. is treated as a 32-bit value. 

* Left shifts of more than 31 give a result of zero, 

* Right shifts or more than 31 give a result of sero from an unsigned or 
positive signed value, -I from a negative signed value. 

■ The remainder on integer division has the same sign as the divisor, 

* If a value oi integral type is truncated to a shorter signed integral type, the 
result is obtained hv masking rhe original value to the length of the 

desrination and then sign extcnding- 

* Conversions between integral tvpes never cause exceptions to be raised, 

* Integer overflow does not cause an exception to he raised. 
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* Inreger division by rero causes an excepnon to be raised, 

Thi; following points apply to operations on floating types: 

■ The ARM's floating point registers ate wider than stored floating point 
number., so That some values may be computed rn a slightly higher precision 
than the stated limits imply. 

* When a if ub i e or long daub la in converted to ,1 t lost, rounding is to 
the rtf.irtd representable value, 

* C.on versions from floating to integral type- cause excej n=n- m be r.n-vd 

onh if rhe value cannot be represented in a • r. j : ior j- -• i 

Iona .tit in the ease of conversion m an unsigned ini type) 

* Floating point underflow o n it detected; any operation which underflows 
returns Sen >. 

* Floaiing point overflow causes an exception i K* raised 

* Floating point divide by Hero Iouscs an exception to be raised 

EXPRESSION EVALUATION 


The compiler performs the 'usual arithmetic convi rston.s' (promotions) set 
out in the draft standard before evaluating at\\ expression. 

* The compiler may recorder expressions Involving only associative and 
. .tnimurncivc operator*, even In the presence' i»r parentheses, 

* Between sequence point*, the ..unpilur may evaluate expression* in an) 
order, regardless of paremhese*. Thus the side effects of expressions 
between sequence points may occur in any order. 



* Similarly, the compiler may evaluate function arguments in any or Jen 
moreover, this order may change from release to release. 

■ The unnrv + operator, as defined in the draft standard, given a means of 
specifying a sequence point other than the defined sequence points, 

IMPLEMENTATION LIMITS 

The draft standard sets out certain minimum 'translation limits' which a 
conforming compilet musi tope with: you should be aware of these if you 
are porting applications to other compilers, A summary is given here- The 
'mem' limit indicates that ni> limit i> imposed other than that of available 
memory. 


Description Requirement 

Archimedes C 

Nesting levels of compound statements and 

iteration/sclcCT v m control structures 

15 

mem 

Nesting levels of conditional compilation 

6 

mem 

Declarators, modifying a baste type 

12 

mem 

Expressions nested by parentheses 

12? 

mem 

Signiticant characters 

in intermit identifiers and macro names 

31 

256 

- in c sternal identifier* 

6 

256 

External identifiers in one source file 

511 

mem 

Identifiers with block scope in one Mock 

127 

mem 

Macro identifiers in one source file 

1024 

mem 

Parameters m one function deflnitlon/call 

11 

50 

Parameter* in one macro definition/invocation 

31 

mem 

Characters in "■tie logical source line 

509 

no limit 

Characters in < string literal 

509 

me i'u 

Bytes in a single object 

32767 

mem 

Nesting levels tar included files 

9 

mem 

Case labels in a sw:: :r. statement 

255 

mem 

ate#it 'registered [unctions 

32 

33 


JO 
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DEFINITION 


This chapter discusses aspects of the compiler which aren't defined hy the 
ANSI draft standard! hut fire implementation-defined and must he 
documented. 

Appendix A.6 of the draft standard collects together informal bm aboul 
portability issuer section A. 6.3 lists those puinrs which are implementation 
defined, .and directs that each implementation xhall document iis behaviour 
in each of the areas listed, This chapter corresponds to appendix A.6.1, 
answering the points listed in the appendix, under the same headings and in 
rhe same order. 

ENVIRONMENT (A.6.3J) 

* Argument to ir.ain 0 &r* the words of the command tine, delimited by 

spaces. 

* The standard input. output and error streams, st&irs, stdout, and stdftJrr 
can be redirected at runtime in the following way. For example, if copy is 
a compiled and linked program which simply copies the standard input to 
the standard output, the following line: 

*copy { < inf He \ 

runs the program, redirecting stdin to the file in file. Note that 
•copy { > out file \ 

redirects both s t dout and st d- rr to the file out f lie; it is nut possible 
to redirect stderr alone, 

* Command-line argument- redirecting stdin or stciout do not appear in 
rhe list of argument* tu Mini). 

* For full details ol redirection in Arthur, see the Archimedes Projjiamttier's 
Reference Manual, volume 1. 




IDENTIFIERS (A.6,3.2) 


* 256 characters are significant in idenritters withiiur external Linkage, 
i Allowed characters are letters, digits,, and underscores,) 

* 256 characters are significant in identifiers with external Linkage {Allowed 
characters are letter-, digits, and underscores, ) 

* Case distinctions arc significant in identifiers, with external linkage. 

CHARACTERS (A*6 3 * 3) 

The characters in the u>uree character set arc to 150 8859-1 (Latin 
Alphabet]* # superset of the s-candard A SC IS character 5er The printable 
characters are ihcsc in the range 52 ro ! 26 and 160 ro 255. All printable 
characters may appear in string or character constants, and in comments. 

* The execution character set is identical to the source character set, 

* There are four chars in an i nt. Thu hyies .ire ordered from least 
significant at rhe lowest address ro most significant at rhe highest address 

* There are eight bits in a character in the execution character set, 1 he bits are 
ordered such that the leftmost bit is most sign it leant - 

* Characters o! the source ehara<-Eer -ct in -mm: literals and character 
constants map identically into character* in die execution character m- 

m A character constant containing more than one character has the type int 
Up to four characters of the constant art represented m the Integer value. 
The first character contained in the constant occupies the lowest-addressed 
byte of the integer value" up to three following characters are placed at 
ascending addre^sc*. Unused bytes are filled with the NUL character This 
is no t portable - 

* A 'plain 1 char is treated o unsigned* 


32 



TANDARD IMPLEMENTATION 
DEFINITION 

* Escape code* are: 


tscape >eq Lienee 

Char value 

Description 

\ a 

7 

Attention ibetl) 

\b 

ft 

Backspace 

\f 

12 

Form feed 

Vn 

10 

Newline 

\r 

U 

Carriage return 

\t 

9 

Tab 

\v 

u 

Vertical tab 

\ xnn 

tin 

ASCII code ki hexadecimal 

\ nnn 

nnn 

ASCII o de in octal 


INTEGERS* A.6.M > 

The repmcmaik>m and >er 1 uf values of the integral types have been set 
out nbi>ve [ft J rnpLjmentaiicm deoiits. Data elements, Note also that; 

* Tlie result of converting on integer ri i shorter signed integer, if the oduv 
cannot be represented, k ;i> it the hr- in tbs- I’rigifiml value which cannot be 
represented in the final value were marked - ■ 141 . and the resulting Integer 
sign-extended. The same applies when you convert an unsigned Integer to a 
Signed integer of equal length- 

* Bitwise operations on signed integers yield the expected result. gu en two’s 
complement representation. No sign extension taker- pla^e, 

■ The sign of the remainder on integer division is rhe same as defined for the 
function dlv (] - 

* Right shift operations on signed integral types are arithmetk- 

FLOATING POINT (A-63.5) 

The represent at ions and ranges of values of the floating point type> have 
been given above in Implementation detail, Data elements. Note d-,o that: 



* When a floating point number is convened to a shorter floating point one, it 
is rounded to the nearer representable numbcr. 

* The properties of floating point arithmetic accord wiih IEEE 7^4- 

ARRAYS AND POINTERS ( A-6-3-6) 

The ANSI draft standard specifies three areas in which rhe behaviour of 
arrays and pointer* must be documented, The points to note are; 

* The type 3 l ze_t is defined m unsigned lrsfc. 

* Casting pointers to integers and vice-versa no change of 

representation, Thus any integer obtained by casting front a pointer wilt be 
positive. 

* Tire type pt rd.: ff_t is defined as (signed) int, 

REGISTERS (A.63.7) 

In the Acorn C compiler, you can declare up to six objects as having the 
storage class register. The valid types art: 

* any integer type 

* any pointer type 

* any structure type which contain* only bitfields and which is no mote than 
one word tong^ 

Note that ocher variables, not declared a* register, m.iy he hdd in 
register* for extended periods, and that register variables may be hdd 
in memory for some periods. 
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STRUCTURES. UNIONS AND BIT-FIELDS! A. 6 O. 8 ) 

The Acorn C compiler handles structures tn the following way: 

* When li member of a union is accessed using a member of a different type, 
the resulting value can be predicted from the representation of the original 
type. No error is given. 

* Structures are aligned on word boundaries Characters are aligned in bytes, 
shorts on even numbered byte boundaries and all other lype.^ except 
bitfields. are aligned on word boundaries. Bitfields are parrs of inns, 
themselves aligned on word boundaries. 

* A * plain' bitfield (declared as int) is rreared as unsigned int. 

1 A bitfield which Jiies not fit into the space remaining in an Lr.r is placed in 
the next int- 

* The order of allocation of bitfields within .cs is ^uch rKat the first field 
specified occupies the least ignifiL inT hits of the word 

* Bit fields Jo not straddle storage unit Until bound an es 

DECLARATORS <A.6*3.?} 


The number of declarators that may miNlify a basic type is- limited only by 
available memory. 

STATEMENTS! A.6.M0) 


The number nt "ase values in a svi' eft .statement Is limitwi only by 
memory. 



PRE-PROCESSING DIRECTIVES { A.6,3,1 i) 


■ A slnglc-chafflCtw character constant in a pre-processor directive cannot have 
a negative value. 


* The standard header tilts art contained within the compiler itself. The 
mechanism for translating the standard suffix mechanism to an infix notation 
is described in Running r/ic Compiler Maming nmtendons, 

* Quoted names fot Includable source tiles are supported, The rules lor 
directory searching are given in Running the Cnmpji'i.T Crm/rnllmg i/uf pre- 
processor. 

* The recognized Kpragra directtve- .nJ rheir meaning are described in 
ffFVapnn dfrecthti * 

LIBRARY FUNCTIONS (A-6.T12) 

When ii'ing library functions m the Acom C compiler, note the following 
points: 

* .The macro NULL expands to the integer constant 0, 

■ If a program redefines n reserved external identifier, then an error may 
occur when the program ls linked with the standard lihr-anc' If it is nor 
linked virh standard libraries, no error will he defected 

* The assert I I function prints the following message 

* T * assertion failed: expT<sii£m, file filename, linelinif- 
n umber 

and then calls the function it r ri. I), 


The functions: 





is alrmm \) 
isa1pha l) 
iacntrl() 
ifflower (} 
isprint () 
isupper l ) 
ispunct I ) 
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usually test only for character whose values ire in ibe range 0 no S 27 
{inclusive! Characters with values greater than 127 return a re&ulr of 0 for 
all of these functions, except tscntrl i) which re r urns norwero for 0 to 32 
(excluding .n, \r. \v and Vt) and 12S to 255. 


After the call set locale [LC_CTYFE* "IS 1885^-1" l the following 
ru!ei apply for characters; 


0 tti 31 except rs, \r, \ v and \t are control characters 

US to 159 are control characters 

L92 to 223 cxk'rp! 215 are upper case 

224 ro 255 except 247 are lower case 

160 ro 1^1, and 215 and 247 are punctuation 

The results returned by the functions reflect this. 

* The mathematical functions return rhe following values on domain cron 

Function Condition Returned value 


log{X) 
logic(x) 
sqrt ix] 
atanZ fx#y] 
asin[xj 
acos fx) 


x <» 0 
x <■ 0 
x < D 
x - y ** D 
aba(x) >= 1 
absixi >= 1 


-HtJSE_VAL 

-KUGE_VAL 

-HUGE_VAL 

0.0 

VV2 

0.0 


Where - HUGE 7AL is written above, a number is returned which is defined 
in the header h ..math.. Consult the er t no variable for the error number, 
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The mathematical functions do not set err tic on underflow range errors. 
The set jrnp \ j function may be called in any cxprestioti context,. 

The net of signals for the signal () function is as follows' 


SIGAERT 

SIGFPE 

5IGILL 

STGIN7 

5IG5EGV 

3IGTERM 

zlGSlkK 


Abort 

Arithmetic exception 
Illegal instruction 
Attention request from user 
Bad. memory access 
Termination request 
Stack overflew 


The default handling of all che signals recognised is to print a suitable 
message followed by .3 stack backtrace This default behaviour applies at 
program startup. 

Hie liter line of m text stream does not require a terminating newline 

character. 


Text lines consisting solely of space characters followed by a newline 
character are read back exactly as written. 

No HOt characters are appended to a binary output stream. 

File buffering is performed as defined m the draft standard (section i.dT). 

A zero-Length file does exist. 

The validity ol tile names is defined by the host computer’s filing .system. 

The same file Can he open many times for reading, and once tor writing or 
updating. A file cannor however he open for reading on one .stream and for 
writing or updating on another 



s 


TANDARD IMPLEMENTATION 
DEFINITION 


* Note Jrhe following points about library function*: 


remove < 1 

Cannot remove .in open file. 

rename ( 1 

The effect of catling the rename | ) futunon when the new 
name already exists Ls dependent on the host filing system. 
Nor .ill renames .ire valid: examples of Invfth-J renames 
include ( "net : file 1 % “net : $ . f iie2' T ' ;■ and 
("net: file! ", "adfs : f ile2"J. 

fprintf (j 

Prints *,p arguments in hexadecimal format as if a precision 
of 8 had been specified. U rhe variant form is stlccicd, the 
number is preceded by ihu character 1 

fstanf ( 1 

Treats p arguments identically to tx arguments. 

fscani [) 

Always treats the character - in a % [ argument a* a literal 
character 

ftell u 

Never reports fa dure 

perror 0 

Generates the following messages: 

Error; 

Message; 

0 

EDGK 

E RANGE 

No error (errno ■ 01 

EDOM - function argument out of range 

ERANGE - function result not 

E3IGNUM 

representable 

ESIGNUN - illegal signal number to 

others 

signal (] or raise [3 

Error code nwmfjer has riD associated 
message 

abort () 

Closes ytl open files, and deletes all temporary files. 
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getenv ( 3 

Reiutm the value of the named Arthur Envirtmmemat 
variablei or NULL if rhe variable had no valuta 
eg root - getenv ( fr C$libroct " 3 ; 

if (root NULL} root = ’'5*arrr,, :lib n ; 

system ( 3 

See the chapter Catting otAcr progTums from C for 3 
discussion tit rhe use of this function. 


strcmp (3 etc The value returned by the memory- and ming-comparison 



function* b in the range -255 to -+255. The value is negative 
if and only it the first string is lexically less than rhe 
second For example, suppose SI nnd SZ differ first in the 
third character. Then srrunp tSIJbiXD ill Sl{2j<32|2|, 

strerror () 

The error messages given In rhi> function are identical to 
those given by rhe p*: r:r ^ i function. 

clock ( 3 

Returtn rhe rime taken by the program dnee ir> invocation,, 
a* indicated by the host's operating system. 

t irr.e (J 

Returns the dare/iitne in second* past l jan-1970. 


set locale (j Only I 1 . 1 - ilw standard LC_ macro* define J lor it- The 
function call see locale tLC_CTYPE, "1508859-1"3 
alters rhe behaviour of the ctyp-e -h functions. as described 
in the set non CHARACTERS i A.6.3.3J above. 

Local rime zones and Daylight Saving Time .irt nor hup lenience J The 
value- returned will always, indicate that the information is not available 



Hrthur operating 

SYSTEM LIBRARY 

To use Arthuriib function*, their dedarai ions must he inserted in the user's 
code hy means of a # include (me. Ah an example, here is the ‘hello 
world' program again. here using the mod* ( ) Junction to change screen, 
mode* 

finclude <stdio.h> 
linclude <Arthur.h> 
int main() 
i 

mode f 7} ,* 

printf("Hello woridEYn") ; 
return 0; 

) 

When the above program is compiled and linked, the -atthur option has 
to be used: 

cc -arthux hello 

This causes the linker to use the art nut lib library in addition to the usual 
ansilifo one. 


Because it as nuue possible tor the names ol the functions and variables 
declared in h.arthur to clash with other identifiers used in a program, a 
facility exists to enable an alternative ser of name-, res be used. These names 
are longer, bur are less ti.kel\ ro clash. 

If the macro symbol AFTHvB KE W_W AME5 is defined before the Arthur 
header tile is included, then ill chi names documented in this chupter must 
he prefixed hy a r t _ before they * .m be used. Here is yet another version 
of the hello program using this method: 
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#define ARTEUR_NEW_MAME5 
ft include <stdio,h> 
ft include <Arthur,h> 
int main() 

I 

a.ri_ii!i{Mje (7) ; 

printf ("Hello worldl\n H ); 
return 0; 

J 

An alternative wav of achieving the same effect as the #def me line above 
would be to list 1 the command line option -EARTH UR NEW _NAMES- 

GENERAL ARTHURLIB FUNCTIONS 

These functions deal with general I/O features ; i Arthur, including 
graphics, sound and keyboard En iccrhCFul their functionality emulates that 
of similarly named BASIC keywords- Buef descriptions arc given below, 
hue you are recommended to refer to the BASIC keyword section of the 
User Guide for comprehensive descriptions. 

Functions such .is os file U me essentially those described in Jetad in the 
ATtfiur Programmer's Re/erence Manual Any C structures referred to arc 
defined in the Arthur header fik <Atth.UF*ti> (it 
$ , arm, cl it . h . Axthutl In the function declarations the ANSI 
prototype facility to give names as well j? types to arguments is med- This 
makes the arguments' use a little more self-explanatory. 

Screen calls 

void circle (int x, int y r int rad} ; - Draws a circular outline 
with centre ai c. -ordinates U.y) with radius rac. Equivalent to SW1 
7 5 Plot with R0=4 Rl-x, R_-y followed a SWl OS Plot with 
110=0x95, Rl^rad+x and R2»y 

void ci relef ill (Int is, int y,int tad) Draws a solid clretei, 
argument# as above. Equivalents as above but R0=Qx9P on the second call. 
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Voi i c,g(void) ; - Clears graphics window to the graphics background 
colour. Equivalent to SWI OS_Wr itel+Oxl 0 . 

void els (void i} - Clears rexr window %o the teifr background colour- 
Equi valent to SWI GS_Wr icoI+OxDc. 

void colour lint col) ; - Sets text foreground/background colour to 
col - Equivalent to SWI OS Write I - Oxl I followed by SW! CS_Writei 
with R0 =cal. 

void ru■ sor < i nt typ*#) ; - Alters cursor appearance "Hie* argument 
h:-is the following meanings: 

Type Meaning 

0 Hide cursor 

L Show' cursor 

2 Steady cursor 

3 Flashing cursor 

Equivalent to the GS_ WritaC sequence Dxl 7,1 y. y re,0,0,0,0,0,0,0- 

void draw tint x, int y) ; - Draws a line to the specified aWilute 
coordinates. Equivalent to SWI •>S_Flot wirh RD*i, RI»x anti RZ^y. 

Void dxawby l int dx, r i nr dy) ; Draws a line to coordinates 
specified tderive to current graphics cursor. Equivalent to SWI C5_P lot 
with R.01, Kl*dx and R2-dy 


void fill lint x, int y) ; - Flood-fill an area in the curteni: 
foreground colour, scarring from (x,y). Equivalent to SWI 0S_F . ■ with 

R0=Oxt'5 1 Rl=x imd R2=y. 

void gcDi (int action, Int coll i - Set acdon and colour for 
graphics foreground ■ ir background plotting, Equivalent to a SWI 
QS+Write1+0x12 





fallowed by two DS_Wri i eCs with R0-act ion and RO-col respectively 

void window (int yl r int x2, Int y2);-Set up a 

graphics window. The bottom left and top right comm of the window have 
the cu-ordinaies (xl,y 1) and (x2,y2) respectively Equivalent in the 
OS_wr iteC sequence 0xl6,xL;yl;x2;y2; where a sembcotofi implies the 
value in sent as. two bytes, low byte licit. 

void mode ( int aide] ; - 5c! screen mode in mde. Equivalent to j SWI 
OS_Wtric s]>0jc 1 S followed hy a SWI OS_WriteC with R0=mde- 

vii i move £ int x, inr, y ] ; - Move graphics cursor to absolute position 
(x r yh Equivalent to SWI OS_Plot with R0=4, Rl=x and R2=y. 

void moveby (int dx f int dy] Move graphic* cursor to a position 
relative to in current position Equivalent to SWI ;P_Fiot with RO=0, 
Rl*dX and ftl=dy. 

void crig 1 n £ ini x, in' y) ; Moves the graphics origin to absoluie 
coordinates given. Equivalent to the 0S_WriteC sequence 29 1 xjy.. 

void Colette (int l^int p, int r,int g*lnt bO Physical to 
logical colour definition. The arguments t om",pond to the five byres which 
follow an 0S_Writ eC with R0=0xt3. « logical colour, physical colour. red 
component, green component and blue component- See the description! ot 
VDU 19 in the User tJuide tor more details. 

void l lot (int type , int x, int y Perform an operating system 
plot operation. This is equivalent to a SWf (t' _Pic t with R0= t ypt-, Rl=x 
and R2*y, 

int pcint i : • ' , - rr j J : Find the logical colour of the gmphfe 

pixel indicated b> coordinate arguments. Equivalent to r SWI 
0£_RfcadFo i nr, with R0«x, R.I »y and returning the value m R2 on exit 

■. fit pos (void.]; Return the s-cootJinute of the texi curaor. Equivalent 
m a SWI 05_Byte with R0=0sS6 and returning the value in R] on exit. 
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void rectangle(int x, Lnt y, int width,int height);- Plot a 
rectangular outline The Iir^r rwn atgurnents give rhe co-ordinates of the 
bottom lefr comer (for positive width ind height), Equivalent to the 
following sequence of OS P lot.sr 


R 0 

Rl 

R2 

4 (Move abs) 

X 

y 

i (Line re]) 

width 

0 

i (Line re]) 

0 

height 

I (Line rei) 

-width 

0 

I (Line rei) 

0 

-height 


void rectangle-fill (int X,ifit y, int width,int height}; — 
Pine a sofkl rectangle* Equivalent to a SWI of:_F 1 t with R0=4, R1 =k. 
K2-y followed by a SWI OS_Plot wfth ROOx6] f Rl-width and 
Ri-height. 

void st,r±ngprir.t (char ; - Print 1 ’ the mall'terminated string 

pointed to by st r on the currently enabled (Arthur) output Mrrcaim 
Equivalent us a SWI OS_Wr i teC withR0=s: x 

void rat ( int x r int y ) ; - Position text cursor at (x,y) relative it? the 
text window origin. Equivalent ten a SWI 05_Wr itel-Oxl f toll owed hy 
two calls to 05_WriteC with RQ=X (ben y- 

voi d t i nt ( int type, int in: ■ ; - Set grey level of a colour. The 
first parameter gives the colour whose rint is to be set, as follows: 

T ype Colour 

0 Text foreground 

1 Text background 

2 Graphics foreground 

3 Graphics background 




Equivalent to the OSWri teC sequence Ox 17 >0x11 „t ype,tnt,0A0.0 AO- 

void vdu (.nr. chi ; ■ Sends eh to the current VDU stream*. Equivalent 
io a SWE 0$_tfriteG with R0=ch. 

voi dl vduw (int ch2 ) ; - Sends Chi as two characters to the current 
VDU streams in the order ch2 £ 0xff,{ch2 (m Dxf fDO) >> 3. 
Equivalent to two calls ra SW| OS_WriteC. 

void vduq(int n, . . .) ; - Sends n characters eo the current VDU 
streams, n integer arguments follow the fim argument, and each of these is 
interpreted as a VDU byte. Equivalent to n caJJs to SWI OS_Wr i teC. 

i rit -j-os (void) ; - Return the current text Cursi r y ett-ordinate. 

Keyboard/mouse calls 

int get (v . i ■ - Return a character code from rhe currently selected 

input stream. Equivalent ra a SWI QS_ReadC where RO is returned as the 
result, 

int inkey lint delay) ; - Return a character code from the input 
.stream or keyboard, with timing features las BASIC). Equivalent to a SWI 
OS_Byte with RCMhcSl, R1 - delay - Oxl 0 0 and RZ «d@ 1 ay Gx 100. 
The return value is derived from Rl and RZ on exit 

int mous«X(void); 
int mouse*(void); 
int mouses(void )t 

These three mouse ha net ions rerum the position and button status of the 
mouse. Note dim (hey should not be used with the WIMP functions 
described in the next section - the WIMP system provides special mouse 
functions. 
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Sound calls 

Lnt get beat (void); - Read current beat value- Equivalent to a SWI 
Sound QBeat frith RO-O on entry and using RO on exit as the return value- 

ir.t get bents (void) ; - Read beat counter cycle length. Equivalent to 
a SWl Sound_QBe*t with R.0= - IS on entry and ui-ing RO on exit as the 
return value. 

int gee tempo (void) j - Read rate at which beat counter counts. 
Equivalent to a SWI 5 cm ri d Temp c with RCH3 on entry and us me RO on 

exit as rbe return Value- 

void set_beats (int beats) ; - Sec hear counter cycle length to 
beats, so that it cycles from 0.,beata-l. Equivalent to a SWI 
Sound_QBeat with R0»beat s, 

void set_tempo (int tempo) t - Set rate at which beat counter counts 
to tempo. Equivalent to A SWI Sound_QTempo with RO* tempo. 

void sound I int chan, int amp, int pitch, int dur, int 
when) ; Make or schedule a sound. Arguments as BASIC, ext eft that when 
= - 2 implies an unsynchronised sound evenE . If when ! =-2 then tt is 
equivalent to a SWI Sound_QSchaduie with ROwhen, R1“0 and R2/RA 
tout Sitting packed vetsiotts of rhe first four arguments. If wr en = ilten ir 
is equivalent to a SWI SoundCont rol with R0..R3 set to the fust four 
arguments, 

.void s o unc _o f : : vold); - Denerivate sound system. Equivalent CO a 
SWI Sound_Enable with R0= 1. 

, voj a sound or. (v . i d i ; Activate sound system. Equivalent tu a SWI 
Soufid_£nable with RO“Z* 

void atereo ( i nt chars r int pas) Set stereo positton for 
specified channel. Equivalent to a SWI fiound_Stereo frffh RO®chan, 
Rl"pca, 



void voices i inc vcea) ; - Ser number of active sound channels to 
vets (1 T 2, 4 or 3 ). Equivalent to a SWI Sound Configure with 
RO=vces andRS-.R4=Q- 

MtaceUeneou* calls 

int adval ( int chan ) ; - Reads data from an analogue port or gives 
buffer data- Equivalent to a SWI 0£_Bytf with RO-OjibO and Rl=-rhan- 

The six funccions below provide access to the obvious operating system 
routines indicated hy their names, For details of C strut Eure* involved, see 
the l - Ar chu: header file. Error returns are as for the svri* ( ) function 
see below. 

orror 'osaics (reg set * regs )f - Perform a SWI OS_Args. The 
arguments to the call ate found m the i eg_set struct whose address is 
passed as an argument Qnlv RO ,R2 are used/aherrd by the call. Et there 
w'a- no vrrot. .- .'ll 11 - returned, otherwise a pointer to an er ror structure is 
rerumed. 

error *oabyte ( reg_Mfct ' regs ) ; - Perform a SW] 0S_3yte. The 
arguments to the call are found in tht tea stt struct who>e address h 
passed as an argument. Only RCt-Rc are used/altered by the call. If tbete 
was no emir, ML’LL is returned, otherwise a pointer to an erroi structure is 
returned. 

error *osf ile (OSf i le_biqc}c * pbPerform a SWI Q5_Fi Is. 
The arguments to the call are found in the oaf ile_block struct whose 
address is passed as an argument- If there was no error, NULL is returned, 
otherwise a pointer to an error structure is ret timed- 

error *ds£ind (reg__sei ’ regs) Perform a SWI OS_Find, The 
arguments to the call are round in the struct whose address is 

passed as an argument. Only RO -R2 are used/d re red by the call. If there 
was no error, NULL is returned, otherwise a pointer to an error structure is 
returned- 
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error *ssgbpb (oggbpb_bloclE "pb) ; - Perform a SWI OS_G BPB, 
The arguments ro the ca]I are found in the Q5gbpb_bloc& struct whose 
address is passed as an argument, It there was no error, NULL is returned, 
otherwise a pointer to an error structure is rerumed, 

error 'oswoxdiint type,void T pb > ; - Perform a SWI 05 Word. 
The type argument gives the 0S_Word number, and the pb argument points 
to rhe free formal QS_Wcrd. parameter block. If there was no error, mull i* 
returned, otherwise a pointer to an er r : r structure is returned. 

■insignea rnd (unsigned seedi; - Return a BASIC-type random, 
number, 

reg set swi [int swlNiun, req set " teaE i ; -This alicrtvs general 
access to operating system SWI routines This function does not trap any 
errors. Ir is passed arguments to indicate an action number and a pointer to 
an input "register set' {see h.Art hur), It returns an output 'register pet*. 
Equivalent to a SWI swiNum with R&.R9 >ei up from ' rega and returning 
RC -R9 on exit. 

Note thin the input register set is passed by address whereas rhe result is 
returned as a structure value. Thus a typical cull would look like rhi.si 

myRega = 3 w i (QS_S WI Nurnbe rF r om31 r i ng, & my Re g s \ ; 

Note also rlvat <l an error occurs, it is not reported and there is no way to 
detect it. It is therefore only sensible to use this call for SWIs which will 
"never 1 generate errors.. 

error * swi k i int swiNmn, reg_set *r#gs) ; - This allows general 
access to operating system SWI routines, a* the previous one does. The 
arguments are the same as Swi i I , However, ihe "X" form of $W| swiMum 
Ls used (by setting hit I7h mi that errors may be reported. If the SWI 
executes without an error, MULL is returned. If an error does occur, at 
pointer to an e r i t structure is returned (see Arthur ,h for its fields). In 




either case, ' rega is updated with the return values of HO, R9. ^So in the 
case of an error, recf3->r [ 0 J will alto contain the error pointer.) 


ARTHUR WIMP FUNCTIONS 

Applications working under Arthur are provided vrirh a comprehensive 
System of WIMP lacilities, To use these, the relocatable modules 
WindouHanager and FontManager must be present Richer resident in 
ROM or loaded into the relocatable module area), 

Writing applications to use the WIMP system is straightforward, provided 
you have read the Window manager chapter of the Programmer's 
Reference Manual, You are also recommended to refer to the Archimedes 
Reference Guide. The C interlaces to the WIMP functions are, Therefore, 
listed here wirh only brief descriptions. 

The structures referred to m this secnon are defined in <Arthur .h>. The 
functions are listed below in order of the corresponding Wimp SW1 
number. 

All of the functions have an error * argument to show where to pur error 
data If an error is generated. If there is tio error, the errn^ field of the 
error structure will he zero on return. 

i n t w_initia11ae(e rra r ') ; - Close and del ere a 11 windows; 

return* wimp version number 

int create wind (wind_block error *) ; - Define (but not 
display) a window, returning a window handle. 

int create_iccnGton_blQck i error *); - Add an icon 
definition to Thar ■.-t i window. returning an icon handle, 

void oelet e_wir,d ( int w_handje # error * ) ? - l")eleie the 
window identified by v handle. 
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void delete_ico« (int w handle, int L_handie, error ; 

- Delete the icon identified by i _hand Le from the window specified by 
w_bandle, 

void open_wind £gpen_block *, error * ) f - Make a window 
appear on the screen. 

void c-Lose_wind (i nt w_handie, error *■) ; Remove the windou 
identified by w_handle from the list of active windows. 

int poll_wimp(int mask, univ_biock •, error •); - Ask 
what ro do next. The mask gives the set of disallowed return codes. The 
code of the nest task to perform is returned as the result, mJ the 
information pertaining to it is found in rhe nniv_b l j zk. 

int redraw_wind i redraw_bl0.ck *, error *);- Draw a window 
outline and icons The window to be redrawn is indicated by the window 
handle m the redraw r ck The return value is false (0) if there are no 
rectangles to he drawn - 

int upd|Lte_windlredraw_block % errr r * i ; Return the 
visible portion of a window lor updating If rhe return i- r ise (0). there tire 
no rectangles to update. 

int get _rectangle [redraw block * r error ‘I,* - Get the next 
rectangle in a redraw lift. Returns false £0) if there irt no more. 

void get wind_state\int w_handle, open_block * t error 
* 1 ; • Read the current state of ihe window identified by w hand 1 9. State 
dam is returned In opan_hlock. 

void flet_icpajrtatel ist*te_block *, error Set 

sc me/a U oi an icon’s fliijs The window and Icon handle^ are he id In 
istate block. 



void get_Lcon_'Htate4igtat?_J)loG& 1 , error Mr- Return, in 
T i s tat c-_b lock, the definition of the icon identified by the norm handle 
field of * istate_block . 

void get j}oint__inf 0 £inQti5e_ block ”, error *);-Return ilara 
about the motive point ct. 

void drag_box (dragjblocfc *, error M ^- Start the wimp 
drafting a box, 

void foree_rediaw (redraw block *, error * > j - Forte a. 
redraw of an area of the screen. Only the first five mts in the 
r ■a d r a w_b lock have sign ificance- 

void set jea ret pos ( ca ret_b 1 o zk ’ , e r ro c *) ; - Set the 
position and size of rhe text caret, 

void get a ret cos (caret bl: zk error *);-Geiihe 

J — , —* — 

position And *fre of the test caret 

void create_menu ( menuJblock *, int f int, error M;- 
Lnitialisc a 'pup up' menu sirmerure, 

void decodemenu(menu Jb lock ‘, univ^block - r textbuf *, 
error * > ; - Decode a menu selection. 

void which_icon{which_bIock T f £coniist *, error *i; - 
Look tor icons with particular flag set!mgs. 

v id se‘.extent Eradrawblock M error *);- Alter the extent 
of a window\ work area Only the window handle and first set of four 
coordinates are used from redraw biock- 

void set_point_ shaperpshape_block *, 
screen pointer's shape. 


error * ) i - Set on* 
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void ope n_ temp late {char *namei error * ) ; - Open a file 
called name to allow load teir’pl ate i ) to read d temp I are from it 

void close_template terror * f } - Clcse rhe cni-rtisrly open 
template file 

void load_template{temp_block r th f error ' ) ; - Load a 
window template from the open file into a buffer pointed to by tb->bu f. 
This pointer to a buffer can be can, to a (wind_block * ) and then used 
tm create a window using treat e_wirsd >, ) ■ 
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SSEMBLY LANGUAGE 
INTERFACE 

Object code modules from, the Acorn C compiler can he linked with those 
produced by ObjAsm, provided chat they observe the conventions of the 
ARM Procedure Calf Standard, (.ObfAsni is a variant of the ARM 
assembler A Asm;. AAsm generates directly executable code, whereas 
ObjAsm generates code in a formal suitable (nr linking, it- in Acorn Object 
Format,) 

This chapter gives a brief description of how to handle procedure enrry and 
exit in .-isscrtihly language in order to interface to C, For details on AAam 
and ObjAsm syntax and AOF E'ites, you should consult: 

ARM Assembler and Archimedes Programmer's Reference Manual, ARM 
Procedure Call Standard, 

REGISTER NAMES 

The following name- are Used in referring to ARM registers: 


al 

RO 

Argument l. also integer result 

a2 

Rl 

Argument 2 

a 3 

R2 

Argument 3 

d4 

Rl 

Argument 4 

vl 

R4 

Register variable 

v2 

R5 

Register variable 

v3 

R6 

Register variable 

v4 

R7 

Register variable 

vS 

R0 

Register variable 

v6 

R9 

Register variable 

fp 

RIO 

Frame pointer 

ip 

Rll 

Used a? temporary workspace 

sp 

RU 

Lower end of current Mack frame 

si 

R13 

Stack Lunii 

lr 

RH 

Link address on calls, or workspace 

pc 

R15 

Program counter and processor status 

fO 

FO 

Floating point tesulr 

fi 

FI 

Floating-point work register 



n 

n 

Floating'point work register 


n 

F.i 

Floating'pomc work register 


f4 

F4 

Floating-point register variable (muse 

be preserved) 

f5 

F5 

Floatmg-poinr register variable (must be preserved) 

f6 

F6 

Fluating-point register variable imust 

be preserved) 

a 

F7 

Floatmg'poini regisier variable (must 

be preserved) 


In this section H ‘at i r |’ means at the location pointed to by the value in 
register r; 'jiC l r, ftn !' refers to the location pointed to hy r+n, This 
accords with A Aim 1 * syntax. 

REGISTER USAGE 

The following points should he noted about the contents of registers across 
function calls. 

* Calling a function (potentially) corrupts the argument registers al to a4 , 
ip, _ r, and i . -t 3. The calling function should save the contents of nny of 
there registers it may need 

* Register it u used nt the time ot a function call to pass the return link to 
the called function; it is not necessarily preserved during or hv the function 
cull. 

* The stack pointer sp is not altered across the function call Itself, Though n 
ttihv he adjusted in the course nf pushing arguments inside a function. The 
limit register s 1 may change at any nme, but should always represent a 
valid limit tci the downward growth of sp. User aide 'will not normally 
alter this register. 

■ Registers v I to . ■ , -m l the frame pointer tp, are expected to be preserved 
across function calls. The called procedure is responsible for saving and 
restoring the contents of any of chest registers which it may need to use. 
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INTERFACE 

CONTROL ARRIVAL 

At a procedure call, the convention is that the registers are used as follows: 

* il to rd'1 contain the first four arguments. 

* sp points to the fifth argument: any further arguments will be located m 
succeeding words above [spin 

* fp points to a backtrace structure. 

* sp and si define a temporary workspace of at least 2^6 bytes available to 
the procedure. 

* ir contains the value which should he restored into pc on exit from the 
called procedure, 

* pc contains the entry address of the tailed procedure. 

* si contains a stack chunk handle, which w used by stack handling code to 
extend the stack in a noncontiguous manner. 

PASSING ARGUMENTS 

All integral and pointer arguments are passed ils 32-hit words. Floating 
point ‘float 1 arguments are )2-blt values, double-argument 64-hit values 
These follow rhe memory representation of the IEEE single and double 
precision formats. 

Arguments are passed u> 1 / by rhe following sequence of operations: 

* Push each argument onto the stack, his! argument tiTM- 

* Pop the first four words (or ^ many .ts were pushed, ii fewer) of the 
arguments into registers a l to a4. 
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* Call the function, tor example by the 'branch with link' instruction: 

BL /uncticmname. 

In many cjssc^ it is pcis&ihle to use a simplified sequence with the wmc 
effect (eg load three argument words into al-a 1). 

II more than four words of atgutflenti were p.LiseJ, the calling procedure 
should adjust the stack pointer -liter the call, incrementing it by four for 
each argument word which was pushed jnd not popped. 


RETURN LINK 

On ft turn from a procedure, the registers are set up as lollowttt 

* fp, sp, al, vl to v6 and f4 to have the same values that they contained 

at the procedure: call 

* Any result > rher than a ckuiting point or a multi-word structure value is 
placed in register al- 

* A floating point result should be placed in register fO 
Structure values returned m function results are discussed, below. 

STRUCTURE RESULTS 

A C function which returns j multi-word structure result c* treated in a 
slightly different manner from other functions by the compiler A pointer to 
the location which should receive the result is jddied to the argument list a*, 
the first argument, *o that a dec la ration such as the following: 

s_type a function[int a, int b, Int c) 

I 

5_type d; 

/* . *f 
return d; 

1 
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SSEMBLY LANGUAGE 
INTERFACE 


b in effect converted to this iorm- 

void afunctiante_cype +p, int a, int b, int c) 

{ 

a type d; 

/* */ 

*P = d; 
return; 

I 


Any as5cniblrir*coded functions returning structure results, nr calling such 
functions, must conform to this model in order to interface successfully with 
object code from the C compiler. 

STORAGE OF VARIABLES 

The code produced by the C compiler uses procedure argument values from 
register where possible: otherwise they are addressed relative to f p, as 
illustrated in Esamples below. 

Local variables, by contrast, are always addressed with positive offsets 
relative to sc. In code which ilter- ss, this means that the offset lor the 
same variable wlL! differ from place u< place. The reason tor this approach 
is that it permits the stack overflow procedure to recover hv changing sp 
and si to point to a new stack segment .is necessary, 

FUNCTION WORKSPACE 

The values of sc and £ 1 passed t<- a called function define an area of 
readable, writeable memory available to the called function as workspace. 
All words below [sp J and .11 or above s 1 , #-51 2 ] are guaranteed to be 
avuilable tor rending md writing, and the minimum allowed value or sp is 
s 1-25 6 TW the minimum workspace available is 156 byres. 


Tin 1 C ran-time system, in particular the stack extension code, requires up to 
256 bytes of additional workspace to be left tret-. Accordingly, all called 
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functions which require no more th;m 2 no byte* oi workspace should rest that 
sp docs not paini to ;i location below £ 1. m other words that at least 512 
byte* remain 11 the value in spa less than that in Si, rhe function should 
call rhe sti-tek extension function x$st sck_ over - low- Functions which 
need more than 256 bytes of workspace should amend rhe re.M accordingly, 
and call x$stack overflow I . as described below. The fallowing 
examples illustrate a method of perform tug this test 


EXAMPLES 


The ("■! tow mg fragments of assembler code ft Instate rhe main points to 
consider in interfacing with the C compiler, li you want to examine the code 
produced by the compiler in more detail for particular cases, you can 
request an assembler listing with the compiler option -5- 

This is a function qog t which expect* two integer arguments and uses only- 
one register variable* v’. It talk another function ffff- 



AREA 

iCSScodei , 

CODE, READONLY 


IMF CRT 

1ffff! 



EXPORT 

Iggggi 


qqqx 

DCB 

11 gggg", ft 

; name of fu.nc,, 0 terminated 


ALIGN 


;padded to word boundary 

qggy 

DCD 

iff000000 

+ gggy - ggg* 




idiat, tc start of name 

;Function entry: save necessary regs * and argson 

stack 




gggq 

MOV 

ip. sp 



S IMP’D 

sp E r (al f 

aZ f v 141 fp, Ip, lr # pcf 


SUB 

fp* i Pt 

fpoints to saved pc 

; Test 

workspace size 



CMPS 

sp f si 



BLLT 

1K$stack overflow| 

j MS i r. 

activity of function 


ADD 

vi, vl* 1 

fuse a register variable 


BL 

1ffffl 

l call another function 
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KAssembly language 

INTERFACE 

CMP vl, 59 ;rely on reg* var* after 

call 
3 . - . - 

i Return: place result in al f and restore saved 
registers 

MOV al, result 

LDMEA fp, { vl, Fp, Sp, pc 5 

If a function will need more than, Z5ft byres ot' workspace, ii should replace 
the two-instruction workspace rest shown above with The following: 

SUB ip, sp, frn 

CMP ip, si 

ELLT | yl% st ack_overf low 1 | 

where n i> the number of bytes needed.. Note rhar K$at ack_over f lowl 
musT be called if more than 25b bytes of frame .ire needed, ip must 
contain sp_*needed, shown in rhe example ahove- 

A function which expects more than four word:- of arguments 'hould store its 
argument m the following manner 

MOV ip, 5p ;copy value of sp 

STKFD sp !, {al, al t a3, a 4 ); save 4 Herds of args, 

STMFP spi, {vl, v2, £p, ip, It, pc) 

rsave vl~v€ needed 

SUB fp, ip, #20 ;fp points to saved pc 

CMP5 sp, si ;test workspace 

3LCC |X$Stack overflow| 
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RRORS AND WARNINGS 


When compiling, ihe compiler can produce sm'r nr warning meta-iges of 
several degrees fif importance. They are: 

* Warmne" indicating definite or possible offences against the Jratt ANSI 
standard, 

* Non'serious errors which still illoW code to be pfodticed- 

* Serious errors which may produce loss of code. 

* Fatal errors which stop the compiler from compiling. 

* System errors which signal fault* in The compiler itself. 

Future releases of ihe compiler mav distinguish further errors or produce 
slightly different forms of wording- 

The mesvigo are lifted alphabetic ally in each section 

WARNINGS 

Warning messages indicate legal but curious C programs, offences against 
the ANSI draft. Of possibly unintended constructs. On detection of ,* 
warning ennduinn, the compiler issues .1 warning message, if enabled, then 
continues compilation. 

* it define macro * xx f defined but not used 

* f & " unnecessary for function or array xx 

This is a reminder that if xx is defined as char xx; I C J then xx has type 
char*. There is a similar reminder tor function names also- Example 

static char snesgr] = hello \n H ; 
int main {) 
l 

char *? = (imesg; * mesg already has type char* V 

* actual type *xx* mismatches format * x* 

A type error in a print r or scan f forma? srring. Example: 




int i; 

printf < ,P 1 *iS\ri‘ p , i*; /* fs need char* not int */ 

ANSI 1 xx' trigraph for 1 found - was this intended? 
This helps to avoid inadvertem us*: oe ANSI irtgrnpha Example 

print £("Type "); /* 77/ is trigraph for \*/ 

character sequence /* inside comment - error? 

You cannot nest cotmtienri tn C. Example: 

i* comment out £unc(Ji tar new. ,, 

/* func(I returns a random number */ 
int funcWoid) 

{ 

return i; 

} 

V 

Dangling ’else 1 indicates possible ericr 
Thss hints chat you mav have mU-macched your : fs and else*. Remember 
an else always retell to the nu^i recem utv matched if Use parentheses 
to ft void ambiguity. Examples 

if (a) 
if fb) 

return 1; 
else if (c) 
return 2; 

else ./* this belongs to the If 
return 3 j 


Ca]- Or does it?" 
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* Deprecated declaration of Mil - give erg types 

A feature of rhe A Nib I dratT standard is ihar argument! types should he 
iiu r en in function declarations (prototypes). ‘No arguments 1 ss indicated bv 
void. Example: 

extern lot funcf);/* should have ’void' in the 
parentheses */ 

■ extern 'main' needs tc be t int" function 

This is a reminder that m:nnP is expected to return an integer Example: 

void mainU 

< 


* floating pc-int overflow when folding 

This is typically caused by .1 division by tem in a floating point constant 
expression evaluated at compile rime. Example: 

#define lifll 1 
Hdefine eps 0.01 

static float a = eps/f1)f ' -im-1 yields C * 

* floating to integral conversion failed 

A cast (possibly implicit) of a floating point comram to ,m integer railed at 
compile time- Examples 

static lnt i tint 1 . 1 . Ge 20 ; ' maxint Is about lei Cl * f 

* formal parameter ' xx 1 r.ot aeciared - r int r assumed 
The declaration of a function parameter is missing. Example: 


int fone CaJ 

/*a should be declared here or within the parentheses *7 
i 





Format requires nn parameters , but. .tun given 
Mismatch between A pi nr f nr scanf formal siring and its nr.hear 
arguments. Example:. 

printf ("Id, 1} ; /* should be two inta ■/ 

function xx declared but not used 

The (static) identifier xx was declared but not used within the source file, 
illegal format conversion ’lx’ 

Indicates an dleeal conversion implied, by a print f or scanf format 
string. Example: 

print f ID); /* no such thing as %w V 

implicit return in non-void function 
A non-void function may exit without using a return statement, hut won't 
return a meaningful result. Example: 

Int func(int a) 

I 

int b=a*10 r ' 

no return <expr> statement * 


implicit return in non-void xx{) 

As above. 

Incomplete format string 

A mistake in a • rintf -.if scanf format string. Example: 

printf ("Score war ^d* score ); /* 2nd I should be 

II */ 
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* T int jcir() * assumed - 'void* intended? 

The definition of a functiop omits its return parameter type - ANSI define 
the default to be int. You should be explicit about ihc type, using void it 
the function doesn’t return a result- Ex ampler 


main ( I 

I 


* inventing 'extern int xx(h*' 

The declaration of a function is missing Example: 

printf{"Type your name: "If 
/* forgot to #include <stdio.h> */ 

* label xx wus defined but not used 
Example: 


errlab; exiti—1J; * this pcint never referenced */ 

* no side effect in void context: 'op* 

An expression which do» not yield ,my side effect wa> evaluated: it wdl 
have no effect at run-time. Example: 

a+b: 

* non-portable - not 1 char in 'xx' 

Assigning character constants containing other than one character rti an i nt 
may produce non-portable roultv E sample: 

static int exitCede = ^AEEX'; 

p non-value return in a non-void function 

TTil" expression was omitted from a return statement in a function which 
was defined with a nan-void return type. Example: 
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int funcfint a> 

I 

int fc-3*lO; 

return; /* no <e??pr> */ 

] 

omitting trailing ‘ ,0" for char(nn: 

The character array being equated m a string is one character too short lor 
the whole MTing, sti the trailing zero is being omitted Example: 

static char mo3q[14il - 'MG) 19(18 Acorn\n"#/* needs 15 * / 

Re-de f in 1 t ton of #de£ine macro kx 
Redefining n macro can indicate a po«iHe oversight 

Shift by nn illegal in ANSI 3 

ANSI C only illow> sh j rr^ of between V s **nJ 5| {the size of an int in bits), 
i omiant ift' outside <ii rim range but between 52 and 255 (which are 
accept able ti> rhe ARM hardware) produce this message, Shi Its outside The 
range 0 to 255 produce the next warning- Example 

static int mask = 1<<32; /* would g:v~ 0 anyway * 

Shift by rrn illegal - here treated as nti 
This js given for negative const hot shifts or s h j ft* greater than 255 . The 
bottom byre of the number given is used, ie it is treated as ( unsigned 
char) Tin. NB. negative shifts are nut treated us positive shifts in the other 
dtrcctTom Example; 

p-rintf ( H %dVn ,, rl«-2) ; 


1 short * slower than *int- on this machine 

For speed you «re i id vised to me in is rather than shorts where possible 

Tim is because of the overhead or pcifunoinf implicit casts from short to 
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: nr in expre-ssion evaluation, However, snorts are half the sue of i rit*, so 
arm vp ot short5 can he useful- Example: 

t 

Short L r j; /* quicker to use ints */ 


* spurious ■ f around scalar Initialiser 

Curly brackets. ;ir<r enlv requited around .-ii rue tore and array initialises, 
Example: 

statir int i - eINIT_IJ; /* don't need brackets */ 

* static xx declared but not 4Sed 

A static variable wav Jin: lureJ in a tile hut never used in it Ir is therefore 

redundant. 

* 'struct' ta«7 'x.x" not Jefined 

It i-, possible for ,1 st r i at to he declared before the body nf the 

structure U defined, ro allow for mutu.illv rtrUTeneing structures, This 
warning implies that the und of the block containing thi. incomplete 
definition was encountered without the foil definition being given Example; 

1 

struct 3 1 /“ forward reference */ 

Struct t \ 

struct s *sp; ■ ‘ reference to struct 3 */ 
int i; 

} 

/* forgot to define struct s */ 

} 

Certain styles of advanced programming using 'Abstract Data Types' may 
generate this warning frequently in client modules which import ‘opftque" 
types. 
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Undefined macro T jfx T in tif - treated as 0 


Unrecognised #pragma -x 
unrecognised #pragma (no f - H ) 

#pragma directives are of rbe form 

t pragma ~xd 

where x is a letter ;m J is an optional digit- These messages warn against: 
unknown letters and missing -s, Example; 

#pragma stack check(0) /* from some other compiler ‘/ 

use of ' op ’ in condition context 

Warm of such possible errors as = and nor == in an ±f or looping 
statement. Example; 

if ta=b) ( 


variable xx declared but not used 

This refers to an automatic variable which was dec land at the <can of a 
block hut never used within rh.ii block h is therefore redundant. Example 

int func(int pi 

{ 

int at /* this is never used */ 

return p*100; 

\ 

xx treated as xarul in 32-bit implementation 
Hiis message watfii .it rwn's complement .irithmentic 1 & dependence on 
assigning injizaci%e constants to unsigned iiits, and u explains char ints 
and long ints are bevrh 32 bits. 
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NON-SERIOUS ERRORS 

Tlittsr err errors which will allow 'working code ro be produced - they will 
not produce lo&s of code, On detection of such an error the compiler issues 
an error message„ if enabled, then continues compilation. 

■ 1 j, 1 fnot 1 ; ’ \ s<ep$r-ite$ formal parameters 

Incorrect punctuation between function parameters. Example; 

extern int EunCiint a,'inl 5d f 

• "op 1 : cast between function and object pointer 
Casta he tween function and object pointers Lin he very Jansen'.us 1 

One possibly valid (but still very suspect) use is in eiistimj an arrav of int 
into which machine code hits hetn loaded into a function pointer. Example. 

static int mcArrayflOO]; 

/•pointer to function returning void*/ 
typedef void ( r pfv){void)f 

{ {pfv) tncArray) O ; ■ * convert to fn type and apply ■/ 

* 'op': implicit cast of non-0 int to pointer 

Zero, equal to * HULL pointer, is the only int which can be legally 
implicitly cast to a pointer type. Example; 

i 

int i, ’ip; 

ip = i; /* only the constant int 0 can be 

implicitly cast to a pointer type ’ 


* 1 op 1 ; implicit cast of pointer to nan^equa. poirter 

An illegal implicit cas-i has been detected bewteen two different pointer 
types. The type casting must he made explicit to escape thb error. Example; 
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int *ip; 
ohae *cpj 

ip = cp; /* differing pointer: types */ 


* ' op' i implicit cast of pointer to ':nt' 

An illegal implicit cast has ktrn derecced between an integer and a pointer 
Such caM-i must hr made explicitly, Example: 

E 

int i, 'ip; 

i = ip; f* pointer must be cast explicitly m f 


* ' Op' z implicit :-sst f 'xx' to F int’ 

An illegal implicit casi has been detected- 

• ’rights: 1 =■■ : ;: vt- is r 1 xx' ignored. *iien address 

t a ken 

Address uf register vac tables cannot he calculated, su ,in address being 
taken ai a variable with a register * lora^c class ntuseis that attribine r. 
be dropped. Example; 


I 

register int i t 'ip; 

ip = Si; /* fr lorces i to lost its register 
attribute */ 


* ' union 1 td j "m 1 not defined 
See ft hive 

* <i.nt> op <pointer> treated as dnt> op Unt) <pointer^ 
Warns oi an illegal; implicit cast within an expression. Typically op is an 
operator which has no business being used on pointers anyway, such js *_ 
Example: 
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int if *ip; 

i = i I ip.* /* Pitwiae-or On a pointer? I */ 


■ <pointer> op <int> treated an lintKpointer> op <• int> 
A* above bur with tht operands the other way round, 

* ANSI C doe# not support 1 ]?ng float 1 

This used to he a synonym lor ooutU, but t$ not allowed in ANSI C 

* Array 'Dj found 

The minimum subscript count allowed is I i Re man be r thar tin.- subscripts 
go from j , *n-ij Example: 

static lot a [ 0 j; 

* isiiignmftnt t r ■ 1 ?r jt '**' 

You can't assign to objects declared as ;anst Example 

{ 

const int ic = 42; /* initial isat ion ok */ 
ic * /" canT change it now */ 


* comparison 'op 1 of pointer and inns 

literal D (for -« and !-} ia the only legal case 
You cannot use the comparison operators on an integer and pointer type As 
the menage implies, you can only check for ,i pointer being (not) equal to 
HULi (Int Ob Hsample: 

i 

int ir jr■ipf 

j = i>ip; / T can't compare an int and & * int */ 


73 




Control character Gxnn found - ignored 

An unrecognised character was found embedded in your source this could 
he file corruption, so back up your sources! h’ore that 'control code' means 
any non-whitespace, nan-printable character, 

differing pointer types: 'ax' 

An illegal implicit type cam was detected m a comparison operation 
her ween iwn pointers of different types, Example; 


i nt * ip r 
char 'cp; 

printf ] '"sdSn" t ip-^cp) t /* tan 1 * .rompa re these */ 
differing pointer types: 1 

The two subexpression*, of a 7 ; conditional expression operator were 
pointers to different types Exatnple- 


int i, * ipp 

char # epj 

printf ( ,, %p\n ”, i 1 ip : cpW /* can't have char * 
or int * */ 


Digit S or 9 found in octal number 

Octal (base 8) numbers may only have dig ills up TO 7- Example; 

static int i = 01^8: / w probably meant 017 7, ie Oxff */ 

formal name missing in function definition 

This error occurs when u comma in a function definition led the compiler to 

•suspect n furthef forms I puamerer was, going to follow, hut none did. 

Example; 
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int a (int b r ) /* missing parameter */ 

( 


* function prototype formal ' xx' needs type or class * 
’int* assumed 

A formal parameter in a function prototype was no: given a type or class- It 
needs at Least one of these (register be inn the only allowed class). 
Example: 

void funefai; /* I mean int a or perhaps register a */ 

■ function xx may not be initialised - assuming function 
pointer 

A function is nnt a v at table, so cannot be initialised, As an attempt to 
initial if»e rx ha? been made, XX is Treated aa of type tuner ion Example: 

extern int fufic(voidj; 

Static int fn(1 - rune; * the compiler will use 

static int <*£nH) - func? instead */ 

* illegal string escape * \x w - treated as x 
Unrecognised string escape (\ fallowed by a l ha meter) found. 

The \ is ignored. Example: 

printfl"\w "'); /* no such escape *7 

■ junk at end of fxx line - ignored 

The xt is either else or end it - These directives should not have anything 
following them an the line, Example: 

/ ' text a tier the should be a comment * 

ifelse if i 1 isn't defined 
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* linkage disagreement for ’xx 1 - treated as ' xx' 

There was a linkage type disagreement Kir declaration*, eg a function was 
declared as extern then defined beer in the hie as static. Example: 

int £unC(ini aW /* compiler assumes extern here * 

static func{int a) /* but told static here */ 

{ 

■ Missing newline before EOF - inserted 

The last line of the source file did not have it* term inuring end of line 
character, 

* Missing type specifirati on - 'int' assumed 

* more than 4 chars ir ',,.‘ 

\ fitting constant or more than r, iur characters cannot be pijisigncd to a 32 hit 
int. Example: 

< 

int i = '12345'; /* more than four chars */ 


* nc chars ir. .‘haracter cons cant f ' 

Al lent one character should appear in a character constant- The empty 
constant is taken as zero. Example: 

i 

int i = /* Less than one char ”= 1i \0 r */ 

* Omitted <type> before formal declarator - ’hat* assumed 
Thts is given in a formal parameter declaration where a type modifier is 
given hut no haw? type- Example: 

int funct*ai; /* a is a pointer, but to what? */ 
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parentheses (..) inserted around expression following 

! op' 

Paten theses were not present when needed to avoid ambiguity. 

retorn <expr> illegal for void function 
A function declared m void must not return wick an expression* Example: 

void a (void) 

{ 

return Qt 


size of ‘void" required - treated as 1 

This indicate* an attempt ui do pointer arithmetic on a vo id *, probably 
indicating an error. Example 

{ 

void *vp/ 

vp++; /* how many bytes to increment by 7 */ 

size of a. [] array required - treated as [1] 
lr an array is declared as having an empty first subscript sice, the compiler 
cannot calculate the array's size- It therefore assume* The first subscript 
Limit to be E if necessary. TTil-s is unlikely no he helpful. 

extern int array [] [101 ; 

static int s = sizeof ■;arrayl ; /*ean , t determine this*/ 

size of function requited - treated as size of pointer 
The compiler cannor know the site of a function at compile time, r^o instead 
lr uses the site of ( * M I. Example; 

extern int fund(void); 
int main(void) 




int i 


s iieof(fjnc); 


( 


sizeof <bit field> illegal - sized fintl assumed 
Bitfields do raoi necessarily occupy an integral number of bytes bur they are 
always pans of an int, so the size of an int is used instead. Example: 

struct s I. 

int exp t 8; 
int mant ; 23; 
int 3:1; 

}; 


int main(void) 

{ 

Struct s sty 

int i ” sneof (St + exp) ; /* eanVt obtain this in 

bytes */ 


Small (single precision) floating value converted c 

0.0 

Small floating point value converted to 0*0 
A floating point constant was so small that it bad ro be converted to 0,0- 
Example: 

static float f = l.OOOle-18 - 1.0e-39; /* le-^2 too 

small for 
float */ 


Spurious relif ignored 
spurious #else ignored 
Spurious #endlf ignored 

One of iKese rhtee directives was encountered outside of any #if nr 
tiifdef scope, Example: 
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#if defined ayrn 
lendif 

#else /* this one is spurious */ 


struct component xx may not be function - ^issuming 
function pointer 

A variable such as a structure component cannot be declared to h ave type 
function, only function *. Example; 

struct s ( 

int f n (1 ; /* compiler will use int */ 

char c; 

1; 

type or class needed (except in function definition} - 
int assumed 

You can't declare a function with neither a return type nor a storage class. 
One of these rtnist be present. Example: 

fane(voidI; /* need, eg, int or 3tatic -/ 

Undeclared name, inventing f extern int xx’ 

The name XX was undeclared, so the ANSI default type extern int was 
used. Example; 

int main(voidJ £ 

int i = j; /'■ j has not been previously declared*/ 


variable xx may not be function - assuming function 
pointer 

A variable coranut he declared to have type function, only function *. 
Example: 




ins: main(vDid) 

{ 

auto void in (void); /* treated as void 
[*fn){void); 

*/ 


SERIOUS ERRORS 

These arc emirs which will probably cause loss of generated code. On 
detection, of such an erior, an error message is issued., and compilation stops, 
The compiler will at tempt to continue and produce further diagnostic 
messages, which arc sometimes useful, but will delete the partly produced 
object file. 

* (error encountered ’*xx w 

Source intent ion-illy producing an erroT with a (error directive. Example: 
#if CHA£_BIT != S 

(error This program heeds eight-bit characters 
(sndif 


* (include file 11 xx" wouldn't Open 

* (include fi_e <xx> wouldn’t open 

Probably caused by a spelling: mismke in the tile name. Example 

((include <stdef.h> / * missed Out a s d‘ */ 

* i***’ must have exactly 3 dots 

Hus is caused b\ a mistake in a function prototype where a variable number 
of arguments i> ?peciheJ, Example- 

extern int printficanst char * format r i; /+one . too 

many*/ 


SO 
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* ' | ' -■£ function body expected - found 'jcx 1 

Thi*! produced when ihe lirsr character after the formal parameter 
declarations uftt function is noc the i of the function body- Example: 

int funcCai 
int a; 

if {a) ♦♦♦ /* omitted the l */ 

• 1 \ T or cident ifiet> expected after ' xx\ but found 'yv 1 
xv ts typically struct or urii on. which must be followed either by the Tag 
identifier or tin’ open brace of the field list. Example: 

struct * f red; /* Missed out the tan id ■ / 

• 'm 1 variables :way not be initialised 

■ " op't cast to ‘xk’ illegal 

• ' op r : cast to non-equal " xx 1 Illegal 

* r op r : illegal cast of ' xx p to pointer 

* ‘op": illegal case to ‘xx’ 

These: errors report various illegal casting Operation* Examples: 

struct s £ 

int a, b ? 

I; 

struct t j 

float ab; 

I; 

int it,sin <voidl 

l 

int i; 

struct S Si; 
struct t s 2i 

/* * = *: cast tc * int * illegal */ 
i = si; 

/* f =*s cast to non-equal "struct' illegal *t 
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si - al; 

/+ <cast>: illegal cast of '"struct 1 to pointer */ 
1 = Mint *) jalf 

/* <cas9t>: illegal cast to t int' */ 
i = tint) s2* 


'opM illegal use in pointer initialiser 

{Stark:} pointer initialisers must evaluate to a pointer or i pointer constant 

plus or minus an integer -constant. This error is utten accompanied by others. 

Example: 

extern int count; 

Static int ^ip * fccount T 2; 

xx may not have whitespace in it 

Tokens such as the compound assignment operators (* etc) may not have 
embedded whitespace characters in them. Example: 

( 

int 1; 

i + = 4tt /* 3F ace not allowed between + and = */ 


<cotnmand> expected but found a 'op 1 

This error occurs when a {binary) operator is found where a stufemcnr or 
side-effect expression would be expected. Example: 

if la) /10; /* mis-placed > perhaps? * 


Expressions expected but. found 'op’ 

Similar in above. An iiperaTor was, found where an operand might 
reasonably he expected, Example: 


fund f»10j ; /* missing left hand side of » */ 
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■ cidentifier> expected but found * xx' in ’enum' 
definition 

An unexpected tolt-en was found in die list of identifiers within rhe braces if 
an engm definition Example: 

enunt colour {red, green, blue ,j )j /* spurious ; V 

* \£space> and \<fab> ar* Invalid string escapes 

Use <space> and \t respectively for these characters in wrings and 
character constants, Example: 

print£( M \ Next?")! /* No need for \ T 

* \ i must have 1 element to initialise scalar ir auto 
When a scalar (integer or floating type) is initialised, the cXprtSMon doe?, 
nor have to be enclosed in braces, hut if rhey are present, only one 
expression may he put between them. Ejcnmple: 

static int i - (1,2}; •* Which one to use? */ 

* Array size nn illegal - 1 assumed 

Arrays have a maximum; dimension of Qxfffff f. Example: 

static char diet[0x1000000 ]; /* Too big */ 

* attempt to apply a non-function 

The function call operator ( > was u^ed after an expression which did not 
yield a pointer to function type. Example: 


int i; 
id; 


* auto array 'xx f may not be initialised 
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Automatic arrays {defined in a function) may not have iniTirdksefs. Only 

scat Ic arrays may. Example: 


int main() 

{ 

int a[| - [1,2,4,8j16,32,64,128|/ 


Bit fields do not have addresses 

Bitfitfld-S do nut necessarily lie on addressable byte boundaries, so the i 
operator cannot be used with them. Example: 

struct s i 

int hi,h2 : 13; 

I; 

int main(void) 

l 

struct s si? 

short *sp ■ &sl*h2; /'can't take & of bit field*/ 

Bit site nn illegal - 1 assumed 

Bitfields have a maximum permitted width of 32 hits a.s they must fit in .1 
single integer Example 

struct s { 

int fl : 40; /* This one is too big V 
int f2 : 8; 

1/ 


"break' not in loop or switch - ignored 
A break statement was found which was not inside a for, while or do 
loop or 5witch. This might be caused by an extra 'i, dosing the statement 
premature I v. Example. 
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int ntainfint argcj 

{ 

if (argq -- 1) 
break; 


’case" not in switch - ignored 

A case lube] was iound which was nor inside .1 :’wi' -h statement, This 
might be caused by an extra I, dtistng the switch statement prematurely* 
Example; 

void fnI void? 

t 

case * * 1 : return; 


'continue 1 net in loop - ignored 

A continue statement was found which was not inside a :'or. while, or 
do Loop, This rrughi he caused by an extra , closing the switch statement 
prematurely. Example: 

while icc) [ 

if <dd) /* intended a f hero */ 

error (); 

} /*this closes the while */ 

if tees 

continue; 

5 

H de£ault' not in switch — ignored 

A default label was found which was not inside a switch statement. 
This mLjaht he caused by an extra \, closing the switch statement 
prematurely Example: 

switch fn} t 
case 0; 



return fn(ni; 
ease 1: if (cc) 
return -I; 
else 
break ; 

i /* spurious i closes the switch */ 
de fault: 

error()/ 


Digit required after exponent marker 
A syntax error in a. floating point constant was found. Example: 

a = b*l.le; /* need [+/-]digits here */ 

duplicated case constant: nn 

The case label whose value is nn was found more than once in a switch 
statement Note that tets i* printed as a decimal integer regardless of the 
form the expression root in the .source Example: 

switch (.nj { 

case 1 ’ : 

# ■# s- 

case 1 1 : 

a m 4 

} 


duplicate 'default' :ase ignored 

Two case* in a single switch statement were labelled de f aul f.. Example: 

switch tn> f 

default; 


default: 
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■ duplicate definition of ‘.'Struct' tag 1 xx 1 

There arc duplicate defirutkm* of the rype st ruec xi ( ,. *} ;. 
Example: 

struct s \ int 
struct s (float a,,b;|!; 

* duplicate defin_t..on of ’union 1 tag 'xx' 

There are duplicate definitions of the type union xx (..».} Example: 

union u first i; char oH];); 
union u (double d i char c[B];i; 

* duplicate declaration of. * xx* 

* duplicate definition of "xx 1 

* duplicate definition of label xx -ignored 

These all refer w venous types of duplicated definition. Examples.' 


/* redefinition of lab s , 

/’ redefinition of i "/ 

/* redefinition of fn() */ 


} 

* duplicate type specification ot formal parameter 'xx" 
A formal function parameter had its type declared twice, once in the 
inryumtru list and once after it. Example: 


static int i; 
void fn(void) 

I 

lob: 

* * * 
lab: 

1 

char i i 
int fn() 

{ 
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void fn(int iJ 
int i; 

{ 


/* this one is redundant *7 


EOF in comment 

EOF in string 

EOF in string escape 

EOF not newline after #if... 

These all refer to unexpected occurrences of the end of the source file 

Expected cidentif ier> after 1 xx‘ Put found * xx' 

expected 1 xx 1 or 1 x 1 - inserted ' x* before ' yy* 
expected 1 xx ' - inserted before 1 yy* 

Thi* typically occurs when i terminating semi-colon ha& hecn omitted 
Ivtoie ;i • (Common amongst Pascal pm# rummers) Another case is the 
omission of a dosing hr iclcer or j parenthesised expression. Examples; 

int fit fine a* int to, ine c) 

£ 

int d = e" fb+c; /* missing ) * 

return d /* missing ; */ 

i 


Expecting cdeclarator> or <type>, but found 1 xx F 

XX is typically a punctuation character found where a variable nr function 

tkclamrinn or definition would be expected (at the top level). Example: 

static int 1 = MAX;+ 1 ; /* spurious ; ends expression */ 

’goto 1 not followed by label - ignored 
Sdf explanatory - 
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Grossly over-long floating point number 
Only a certain number of decimal digits arc needed cn specify .-i floating 
point number to the ;k-ctlTftty tlist it can be stored to- Tbn number ot ^iijgLr.s 
was exceeded bv an unreasonable amount 

Grossly over-long hexadecimal constant 
A hexaJccim.il const.ins 1™> an excessive number i.’ii leading :eto:-. not 
affecting its value. 

Grossly over-long number 

A constant has an excessive number ol leading :cros, not affecting it* value. 

Grossly over-long string 

Hex digit needed after Ox or OX 

Hexdecimal constants must have at least one digit From the set 0 . . 9, a . . f, 
A, .F following the Ox. Example; 

int i = jxqs ■■ * illegal -iex char ■ • 

Identifier (xx) found in ■-abstract declare -«;■> 

The si zeof ( } function and cast expressions require abstract dedaraiofs, ic 
types without an identifier name This error is given when an identifier is 
found in such a situation. Examples 

i = (int j) ip; /* trying to cast to integer */ 

1 = sizeof(char str[lO])f * probably just mean 

slzeofjstr) V 

illegal bit field type * xx' - "int* assumed 
Int (signed or unsigned) is the .mlv vulid bitfield type in ANS3- 
confnrming implementation*,. Example 

struct s ( char a : A; char b : A:\; 

Illegal In #lf <expression>: xx 
illegal in case expression (ignored): xx 




■ illegal in constant expression; xx 

* illegal in floating type initialiser: xx 

All of rh^se errors occur when a constant is needed at compile time hm a 
variable expression was found. 

* Illegal In 1-value; 'emjra' constanc ' xx' 

An incorrect attempt was made to assign, to an errum cons run r This could be 
caused by crus-spell mg an enurr or variable identifier Example: 

enum col j red, green, blue),; 
int fn (J 
t 

int read; 
red " Id; 


* Illegal in the context of an .-Voiue: 'XX 1 

* Illegal in ^value: function or array ' xx' 

An incorrect dittmpE was. made to assign to xx, where the object in question 
Is not assignable Un lvalue) Vuu can’t, for example, assign in an array 
iiiitue or a function name. Examples: 

f 

inf a, b, c; 

■= ? c : c = ID; / ■ ?: can't yield 1-values + */ 
if (a) /* use this instead */ 

b = 10; 

else 

c = 10; 


or, in the same context, 

* (a ? ib: *c> = ID; 
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* illegal in static integral type initialiser: xx 

A constant was needed at compile time but a suitable expression wasn't 
found. 

■ Illegal types for operands : 'op' 

An operation Wfls attempted using operands which ate unsuitable for the 
operator in question. Examples; 

I 

struct Sint a*b;3 s; 
int i t 

i = “g; /* can’t indirect through a struct */ 

s * s+s; /* can’t add structa */ 


* Junk after #if <expression> 

* Junk after Iinclude n xx n 

* Junk after ^include <xa> 

None of these directives should have any other non-whitespace characters 
following the expression/filename, Exatuple: 

#include <stdio.h> this isn't allowed 

* label 1 xx* has not been set 

An attempt has been made to use a label that ha- not been declared in rhe 
current scope, after having been referenced m .7 qot 0 statement. Example; 

int main(void) 

< 

goto end; 

\ 


* Misplaced '{ 1 at top level - ignoring block 
>; J blocks can only occur within fucti-nn definitions. Example: 
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/* need a function name here */ 

l 

int if 


Misplaced T ielse ,r ignored 

Ati else with no matching i i was found, Example: 

if (ec) /* should have used \ } */ 

1=1 i 

j -2; 

else 

k = 2i 


Missing itendif at EOF 

A # l t or * i f rie f was 'till active at end of the source hie. These directives 
must always be matched with a ^endif- 

Missing f T '> In pr^-processor command line 
A line such as #inelude "name has the second Ph missing. 

Hissing *) 1 after ax(.., cn line nn 

The closing bracket Or comma separating rhe arguments) ni a macro call 
was omitted. Example 

^define rdch(p) icb=*p-~;i 

i 

rdcfclp /* missing ) */ 


Missing or 'after *define xxl..- 

One of the abovr charaLfer.'i was omitted after an identifier in the macro 

parameter list* Example: 

^define rach(p {Ch - *p:++; I 
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■ Missing *<* or * n h afier If include 

A i include filename should be Within either double quotes or angled 
brackets, 

* Missing identifier after idefine 

* Missing identifier after #i£def 

* Missing identifier after tfundef 

Each of these directives should he followed by a valid C identifier- 
Example; 

^define P at 

* Missing parameter name in #de£ine . . . 

Mu identifier was found after a 1 , ' in a maerti parameter liu Example; 

■^define rdctitp,) \ ch“*p+ + ; } 

* Mussing hex digit (si after \x 

The string escape \x is mtended to be used to insert ASCII coded 
characters in a string, but was incorrectly used here, it should be followed 
by between one and three hexadecimal digits- (On the present system, ii 
there are three digits following the the first one i« ignored.) Example; 

printf j ”\xxx/"l ; /* probably meant "Wxxx/" * 


* No after #if defined, i., *. 

The def: ned operator expects an identities optionally enclosed within 
brackets. Example: 

#if defined(debug 

* No identifier after #if defined 

See above. 
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non static address *xx* in pointer Initialiser 
An attempt was made to lake the addreas of an automatic variable in an 
expression used to initialise a st 1 r ~ : r. pointer Such addresses arc not 
known at compile-time. Example: 


{ 

int if 

static int * ip = Si; /‘St not known to compiler*/ 

flon-formal 'xx' in parameter-type-specilie: 

A parameter name used to declare the pans meter types did not actually 
occur in the parameter b*t of the function. Estample: 


void fn(a) 
int 

t 


Number nr too large fox 32-bit implementation 

An integer constant was found which wu* mo large to fit in a *>2 hti int. 

Example: 

static int mask = 0 x 300000000 ; •* 0 x 80000000 intended?*/ 
Overlarge floating point value found 

Overlarge (single precision} floating point value found 
A floating pciinr constant has been found which is so large rhai ft vi.ili nor nr 
in i floating point variable. Examples: 

float f - Ie 4 Q; /* largest Is approx le 38 for float */ 
double d = Ie 31 C; /* and 1^309 for double */ 

quote (" or ') inserted before newline 

Strings and character constant* are not allowed to contain unescaped 

newline characters Use \ ■■ r, 1 > to allow strings to sp^n lines Example; 
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print f (."Total « 

* re-using 'struct' tag 'xx' as ‘union 1 tag 

There are conflicting ddmitiora or the type struct xx {„ t * j t and 
union xx [ . , , I ;, Structure .md union i,irs currently share the same 
namespace in C, although this not actually ncce&sary. Example: 

struct s lint a,b ;\i 

union 5 (Int a; double d;]; 

* re-using 'union' tag 'xx' as 'struct' tag 
As above, 

* size oi struct 'xx* needed but not yet defined 

An operation requites knowledge of the jshe vf ihr struct, bur rhu wa* nor 
defined- This error in likely 10 accompany others. Example: 


struct s; 
struct s ■‘sp; 
sp++; 


■'* forward declaration *i 
J* pointer to 3 */ 

■'* need size for inc operat ion' 


* size of union 'xx' needed but not yet defined 
See above. 

* storage class 'xx' Incompatible with 'xx’ - ignored 

An attempt was made 10 declare a variable with conflicting Storage classes. 
Example: 

{ 

static auto ln.t i; /* contradiction in terms */ 
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storage class ' xx' not permitted in context xx - 
ignored 

An attempt was ■made to declare a variable whore storage class conflicted 
with as position in. the program. Examples; 

register int i; /+ can’t have top-level regs */ 
void fn(aj 

static int a; /* or static parameters */ 
i 


string initialiser longer than char Inn] 

An attempt was mode to initialise a character array wtih a siring longer rhan 
rhe Array, Example; 

static char atrflG; - "12345678901234*; 

strode ' xx' nest be defined for [static) variable 

declaration 

Before you can declare a static structure variable, that si rue lure type rnu.vi 
have been defined. This Is w the compiler knows, how much storage to 
reserve for it- Example*. 


static 

Struct 

s si; 

/* 

s not 

defined ’ 

struct 

static 

t; 

Struct 

t tl; 

/* 

t not 

defined *■ 


s ■ r u c t / union 1 xx f has no xx fie1d 

The held name used with a . or -> operator b not a valid one for the union 
or structure type 'xx' being referenced. Example: 

struct s (int a,b;l? 

{ 

struct s si; 

sl.c * 3; /* no c field */ 
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* struct/un t on 'xx 1 not yat dafinad - cannot be selected 
from 

The srructure or union type used as the left operand of a , of -> operator 
has not yet been defined so the field names ate not known. Example: 


stru.ct s 3 l; 

si.a * 1 1 ; / T don H t know field names yet */ 


* Too few arguments to macro xx { . . . on line rrn 

* Too many arguments to macro xx (... on l:ne nn 

The number at arguments used in the invocation of a macro must match 
exactly the number used when it was defined, Example 

* define rdcb(ch r p] while ( (ch *■ *p++)==' 1 ); 

rdch(ptr} ; /* need ptr end. ch */ 


* too many initialisers in (] for aggregate 

The lisr of constants in a static array or structure initialiser exceeded the 
number of eletnents/fidds for the type involved. Example: 

static int powers [B] * (0,1,2,4,0, 16,32, 64,128); 

* Too many arguments in function cal_ - ignored 

* type 'xx' inconsistent with *xx* 

* tyco disagreement for *£jc' 

Conflicting types were encountered in function declaration {prototype) and 
its definition Example: 
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void fn finn): 


int fn(ini a) 

{ 


cypedef name f xj!r h used in expression context 
A typedef name was used as a vana hie name. Example: 

typa-def char flag; 


int i = flag; 

undefined struct/union f jcjc f cannot be member 
A st rue t/uni on nor a trendy defined cannot be a member of another 
struct/uni or,« In particular this means that a struct/union cannot be 
a member of itself - circular types arc not allowed, Example: 

struct sl { 

struct s2 type; /* s2 not defined yet * 1 
int count; 


Unknown directive ; %xx 

The identifier following a it did not correspond to any of the recognised 
pre-processor directives. Example: 

#asi? /’ not an ANSI directive */ 

wrong number of parameters to * xX* 

The function xx was called with the wrong number nf parameters, as 
defined by its protype. Example: 


size t strlern (const char *s); 
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{ 

int I = sttTen{str,j); /* only str needed */ 

* uninitialised static (j arrays- illegal 

5 $rtic { ] arrays must be initialised to allow the compiler to determine their 
Example: 

static char str[3f /' needs (} initialiser */ 

* union variable ’ xx‘ must be defined for (static} 
variable declaration 

Before you can declare a nraiic union variable, that union type must have 
been defined- Examples 

static union u ul; /* compiler can't ascertain si * 

* 'while' expected after 'do' - found 'xx' 

The syntax of the do statement b do st&mrumt whi 1& (expression} - 
Example: 

do /* should put these statements in [} */ 

1 = InputLlneU; 

err * processLlneCl)f/*finds err, not while 

V 

while (ierr); 

FATAL ERRORS 

These are causes lot the compiler to £tw up compilation. Error messages 
are issued and the compiler stops. 

* Couldn't create object file 'file 1 

The compiler was unable to open or write to the specified output code file, 
perhaps because it was locked or the o directory does nor exist 

* macro args too long 
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Grossly over-long macro arguments. 


■ macro eKpansion buffer overflow 
Grossly ever-complicated macros were used. 

* No score Left 

out of store (in cc_elioc) 

The compiler has Fun out of memory - either shorten your source programs 
or tree some RAM using rhe ’‘UNPLUG command. To do this, first check 
which modules are present in your machine by rvping ‘MODULES, If rhere 
is a module that you do not currently need, you can release its space by 
typing 

"UNPLUG irrod'ulenajrTG 

It can later he restored using the " RMREINI T command. For further 
derail?,, refer to the wciion entnlej Module in the Arcfciitt&ta 
Programmer's Kjejference Manual, Vol 2 . 

* Too many errors 

More than 100 serious error* were detected 

* Too many file names 

An attempt was made to compile too many files at , mce, 25 l? the maximum 
that will he accepted. 

SYSTEM ERRORS 

There are some additional error messages that can be generated by the 
compiler u it direct* errors tn the compiler itself. Et is very unusual to 
encounter the*' type of error. If you Jn, note the circumstances under which 
the error whs caused and contact your Acorn dealer 
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ECC COMPATIBILITY MODE 


This chapter discusses the differences apparent when the compiler is used 
in TCC mode- When given the -pcc command line flag, the C compiler 
will accept jBerkeley) Unix-compatible C, as defined by the 
implementation of the Portable C Compiler and subject to the restrictions, 
which are noted below. 

In essence. PCOtyle C is Kerniirhan and Ritchie' C, as defined in the book 
The C Froj^irntfimg Language; by B. Kemighan and D Ritchie (KikRh with 
a small number of extensions end clarifications of language features that 
the book leaves undefined. 

LANGUAGE AND PRE-PROCESSOR COMPATIBILITY 

En -pcc mod*, the Acorn C compiler accepts K&tR C . hut it doe* not 
accept many of the old-style compatibility features, the use of which has 
been deprecated .md warned against for many years. Differences arc listed 
briefly below:. 

* Compound assignment operators where (he - sign comes first ate accepted 
(with a warning) by some PCO- An example is =+ instead! nt +* A com C 
doe* not allow this ordering of (he characters in the token 

* The ^ sign before a static iniuaEiser was nor required in some very old 
Ipre-KckR C) compilers. Acom C does nor support rhis syntax, 

* The following, very peculiar* usage 1 es found in some Unix tools pre¬ 
dating Unix Version 7; 

Struct fint d, bf}f 
double d; 

d. a = 0 } 

d.b = Qx.,,.; 

This is accepted hy Unix PCCs and may cause prohlems when porting old 
(and badly written) code. 



WUtns art 1 less strongly types than is its.ua l under PCCs. eri urn ]$ a ncm- 
KikR extension rm C which has been standardised by ANSI somewhat 
differently from the usual PCX" tmplemeni atksn* The compiler warns of this 
when an enurn is encountered- 

dams are signed by default in -pcc rru>de. 

In -pcc mode, the compiler permit- the use of the ANSI ' natation 
which signifies that a variable number of formal arguments follow. 

With the except urn of entstm, the compiler's type check ing is generally 
stricter than FCC's - much more akin ra lint's, in fact- In writing the Atom C 
com pater, we have attempted to strike a balance between generating too 
many warnings when compiling known, working aide* and warning of ptxir 
or non-portable programming practices. Many PCO silently compile code 
which has no chance of executing in just a slightIv different environment, 

We have ined to be helpful to those who must port C among machines in 
which the following varies 

the order of bytes within a word, tc.g- little-endian ARM, VAX, Intel 
versus big-endian Motorola, IBM370), 

the default sire of inc (four bytes versus two bytes in many FC 
im piemen rations), 

the default site of pc inters (not always the v 3rnr a* lnt)- 

whether values of type char default to signed or unsigned char, 

the default handling of undefined and implementation-defined aspects 
of the C language - 

If the verbosity of cc -pcc is found undesirable then nil warning* can be 
turned off b\ usmg the -w command-line flag, 

The compiler's preprocessoff is believed to be equivalent to Unix’s epp, 
except for the points lilted below. Unfortunately, epp is only defined by irs 
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tmplemimrjitLon, and although equivalence Hten tested over .i large 
body of Unis source codm completely identical behaviour cannot be 
guaranteed- Some (if the pome* lisred below only apply when rhe -E option 
is used with the cc command. 

There is a different treatment of whitespace sequence* (benign). 

\<nl^ sf. processed by cc -E. hut passed by epp (making Unes longer 
than expected i cc -e only ) 

Cpp breaks long lines at a token boundary; CC -E doesn’t (this may 
break line-aiie cCUSStfaijifs when rhe source is later consumed by another 
program cc -E only). 

The production of « line " f ile" directives is different ice -£ only). 

The handling of unrecognised ft directives is different (this is mostly 
benign). 

Literal control characters i ause c ro issue a warning (bur they are not 
Lgnorcd as they lire m ANSI mode) 

The 'whitespace control characters' form-feed, carnage-return, and 
vertical-tab are converted to newline. 

STANDARD HEADERS AND LIBRARY 

U?e of the compiler in -per mode preclude* neither the u-se at the 
standard ANSI headers built in to the compiler nor the use of the rutviime 
library supplied with the C compiler 

(.At course, the ANSI library does not contain the whole of rhe Unj\ C 
library, but it does contain almost all the commonly used functions. Beware, 
however, char some functions have different names tor example rhe ANSI 
function strrehr 1) is called v tn^e.v; i i under BSD Unix 
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Also some functions have a slightly different definition, For example, the 
ANSI spt Lnc f ( i returns the number or characters ‘printed', whereas the 
BSD sprint f •: j returns a poster ro the start of rhe diameter buffer- {This, 
docs not matter Li the function is. used in a void content, as is often the 
case,) Fortunately. the important functions such as pi Int £ ( i , f print f (), 
mallfrc t)j stccpy (( * etc-, arc all identical. 

Another h,a-ard is that the 'standard' definitions are sometimes in different 
'standard' places. For example, the A MSI string-handling functions are 
defined in <5tr Lrig,h>, whereas the BSD string-handling (unctions are 
defined in <str mgs , h>. 


Unless the user directs otherwise using - j, the C compiler will attempr to 
smriJify references to, say, cstdic . h> from irs in-store filing system. Of 
course, this header is an ANSI header and is invalid m -pcc mode. 
However, the compiler is able to iwirdi if-eli remporarily into ANSI mode 
when reading In-store headers, switching hack to -rcc mode for everything 
(.-I'm.- Tin- behaviour ■, inn or he exploited to use real ANSI header files; rhe 
compiler mn * inh do tr using rhe tiles it know* uhout (and for which the 
switch to ANSI mode is known to he harmless), 

Time funi,nous are very system-dependent, bur ?hh is well-known within rhe 
C community and doesn’t usually constitute much of n problem in software 
written with portability in mmd. 

Notwithstanding these problems, many simple programs will compile 
immediately using cc -pcc. 
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ALLING OTHER 
PROGRAMS FROM C 


INTRODUCTION 

The C library procedure system t) provides the means whereby a 
program can pa.?,;* a command to the host system’s command line Interpreter. 
The ^emantics or chi? arc undefined hy the draft ANSI standard- 

Arthur distinguishes two Lind 1 , of CLiiTmuuuh. which we can loosely term 
built-in commands and applications. These have different effects* The 
former always return to their callers, Ehe latter return 10 the previously set¬ 
up ‘exit handler' Because of these differences. -:y-' -n i > exhibits three 
kinds of behaviour* This is explained below. 

Applications, in Arthur are loaded at a fixed address specified hy the 
application image. Normally, this is the base of apphiarum workspace. 
0x8000- Vk- r KiLc executing, application* are free to use store between the 
base and end ol apphc.itinn workspace. The end is the value returned by 
SWl 05 _ .-“tF::v Thev terminate with a call of SW| OS Exit, which 
transfer* control to the current exit hnndler- 

When a C program makes the call system < " command " i , the result 
depends on the type of command: 

* A built-in command will execute and return to the C program If there was 
no error, syst em (J returns 0, otherwise ir returns something non-0 (which 
may vary from one release to another) 

• An application will load, possibly overwriting du- C program, execute, then 
return through the exit handler. This is usualh set ro rhe Arthur command 
mode, hut some applications such as Twin and BASIC's 'shell 1 library also 
set up exit handler*- Tile C program effectively loses control the moment it 
does the system f). 

To provide finer control, two variants of system (> are provided. If the 
argument to system ( l begins with CALLi and the callee is a built-in 
command or an application satisfying certain conditions fdeinzrtbed below! 




theft return from system 0 is guaranteed. Similarly., Li the command string 
begins CHAIN; then there will be no return, even if the churned command is 
built on. 

In order lor an application to invoke other applications and have control 
return, lt ts necessary to: 

arrange that the invoking application occupies an address range clear of that 
required by the invoked application, 

sex the end of application workspace below the hast: of the invoking 
application, and 

set art citir handler sn that thf invoking application regains u.mxTol when the 
invoked application exits. 

Note; It is not possible to load Arthur modules from an Arthur application 
unless the relocatable rruxiule area (RMA) has been configured to he 
sufficiently large Where** loading module* from rhe Arthur command 
mode succeeds because it van extend the RMA, rhis cannot be done it there 
is an acme application. 

When rhe library hint r ion system() is given an argument string start mg 
with the characters CALL:, it automatical llv performs rhe second and third 
ot these tasks., before handing the remainder of the argument string to 
OS_CLT to execute- So the C program only h,i>- to worry about the first 
point, avoiding a clash of memory requirements. This can be solved in two 
ways; 

Tire invoking application can be linked to load ut ' fixed high address. Thin 
is nuher inflexible. For example, selecting on address which will allow the 
application to il.il on a range of machine* with differing memory size* 
means wasting memory in rhe larger machines. 

The (relocatable) invoking application can re-load itself at the top of 
available memory. Tho technique has rhe advantage of being more general 
than the first. 



Balling other 

PROGRAMS FROM C 

The invoking application can he linked to be {load-time) relocatable, u*ing 
the linker's- -r^l : cat abler flag Such an application will he loaded at 
OxSOOO if run directly, bur either the application itself can observe that n is 
ninnmg ■*! fW low nn address* find reload itself .i suit.iHe distance from the 
top nf memory, or one can run a small bootstrap application which load*, 
the mam application a. suitable distance from the rop of memory. 

(One might rhink that in the first case, the imnpe could be moved up from its 
current position to a suitable one, then re-entered- Unfortunately, by the 
time the image is entered the relocation rahle has been overwritten, so re¬ 
entering fails). 

Which of these methckL w preferable depend* principally on the sire of 
the application: the larger it die more attractive the houtArrap method. 

The code required is much the same in both cases, and is illustrated by a 
small CLI example i.which uses the Sclf'fdokd method) below. 

Note that, in this example, when the application is reloaded, us arguments 
start at argv ! 2], not a rgv ; I ]; am id is * f go " and argv [11 is 
“<addr:esa>; ", 

Although in this example the required heap site is a constant* che method is 
obviously adaptable to mote complicated values, lor example ii could u>c a 
fixed proportion of available memory* or un amount determined In (some 
property of) the arguments, 

AN EXAMPLE PROGRAM USING system () 

The following example can he found on T he distribution disc with rhe 
filename HowToCs'..!, h is u curntmind line interpreter chat reloads itself a 
fixed distance from the end of store, then prompts for commands which arc 
passed ro Arthur tor execution via sys tem () . Any command - including 
the invocation of another application icq the CL] itself)— can be executed* 
provided that there is enough memory". 
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#include <kernel + h> 

#include <stdio.h> 

* include <stdlib.iL> 

^include <string.h> 

#include <ctype.h> 

I define OS^GetEnv 0x10 
H 1 define MaxHeapSize (32*1034) 

#define LcadFi]eUsingPafhVariable Oxe 

static void CheckError(int status) 

{ 

if (status^- kernel^ERRQF) ( 

_kernel_oserror *err = _kernel_la 3 t_ 0 serror 0 ; 
fprint f (stde tr, "can 1 t reload: * a \ n ”, 

& ler r->errrness ) ) ; 

exit( 1 )} 

\ else if (Status \ * 1 ) ( 

fprintf(gtderr, "ran 1 ! reloadYn"); 
exit ( 1 ); 

1 

} 

static void Self Re load (char" 'name) 

( 

/* This procedure reloads the current application a 
distance below the toe ;:£ merac-ry which allows its heap 
to be of size MaxHeapSize, then enters it with the same 
arguments as it was given this time iano does not 
return). 

Except.: if the application is already at the right 
address, the procedure does nothing and refcuins * 

if the reload fails, in which case a message 
saying sc is produced and execution terminates** 
_kernel_swi_rega regs; 
int 'heapptr - malloc M ) jr 
_kernel_sw ±(05 GetEnv, iregs, fcregs); 

/* (No error possible) 



c 


ALONG OTHER 
PROGRAMS FROM C 


’ regs.ilOJ is our argument acting 
* regs*rl1J is the top of available memory 
*/ 

if Mint) heapptr < rjgs.r[ 1 ]-MaxHeapSlre) ( 

/* we are running too low in store; 

T reload ourselves higher 
*/ 

_kernel_osfile_t!iock osf; 

/’ reload so that the end of the word allocated 

* for heapptr will he MaxHeapSize he',ow the top 
' oi allowed memory 

*/ 

int mybase = Qx9QGQ; 

int newbase = tegs„r[ 1 J’MaxHeapSiae- 

(tint) heapptr - mybase); 

char s-t 256 Jj 

char ■ args = ichar *) cegs* r [ 0 ] ,♦ 
while i, ■ args ! : ’ ■ : aigs + i ; 

.■ * skip ever the application name in 

* our argument string 

*/ 

osf.load = newbase; 

csf ,exec <= 0; / ‘ _oad at our provided address * 

osf.start - (ir.t) H run Spat n 14 ; 

CbeckError( 

kernel_osf ile (LoadPi IfeUsingFathVijriflJfrie, tame, tosf) 
) f 

sprint f (s, 11 .‘HA*K;go • x: s 11 * newbaae , arg£J ; 
system(a); 
f 

tree(heapptr )t 


static int cli(void) 
for an \ 
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char b[2561 * 
int eh, i; 

kernel_oserror *arr; 
err = NULL; 

/* prompt for input,,. */ 
printf{”cli> "3; 

/* skip leading spaces */ 

while I fch = getctstdinl ) -- f 1 ) ; 

i - 0; 

while [ch 1= '\nM [ 

/* EOF means kill cli() */ 

if (eh =*« EOF) {printf ("\n"); return (0); 3 

to Li + -t- J =* ch; 

ch ■ getc(stdi.n); 

1 

bti! = 0; 
if (i !“ 0) I 
char c[25#jf 
int rear 

strtpy(e r "CALL;"); 
street (c, b); 
res = system (c]; 

if (res -- 0) err = _kernel_laat_oserrorO; 

} 

if (err!=NULL) printf("error ii; is\rT, 

err->errnum, 
k {err->errtness 3 3 ; 

} 

return{0); 

} 

int main{int argc, char *argv[]| 

{ 

SelfReloadia rgv1013 ; 
return cli0; 

\ 
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SING THE LINKER 


7"he Linker is an essential program for anyone developing programs in a 
high-level compiled Language on the Archimedes personal workstation* Ire 
purpose is to combine the contents, of one or more object files (ihe output of 
.1 compiler c.it Assembler) wirli one t>r ituice library files, producing a final 
executable program. 

SYNTAX 


The formal of the Link command is:. 

Link -output fitt I options ] /ties 

The files argument is a list of input tricot this is described below, 
-output is the only compulsory keyword* 

Below i 1 ’ a list of the command tine options that the Linker can take. Most 
of these will only be used occasionally! In the descriptions below, the 
important, frequentSv-used options are given first, followed by the less 
common ones. Capital* are used to denote the alternative shortened form 
of the keyword. 

-Output 
-VIA 
-Case 
-ease 
-Verbose 
-Relocatable 
-Dbug 


Name of the linked output lilt 
Use a file to obtain (further) input hie names 
Make marching of symbols case insensitive 
Set base address for output file 

Print messages indicating progress of the link operation 
Generate relocatable output file 

Gen trace an AOF image for use with the Dbug program 


Note* 

* The keyword -t ->: : a is followed by a numeric argument- You cun uh* 
the preim * to specify hexadecimal, and the suffixes k for 2^ and ni 
for Z"°* 

* The default address for the output tile ficSOOd i32KI>. If -dbug 

is specified, the default bn sc address is fie 'ZCK), 



The item fiUs above in « lj.ii of one or more filenames, separated by 
spacer This pm of the command mum he given Bach of the liles in 
[he list mu*! he Ln Acorn Object Format Ectimpilied tiles) or Acorn 
Library Formal Etibrarie?). They may contain reference 1 ? to external 
objects (procedures and variables) which the Linker will at Tempt m 
resolve by matching them against definitions found in other files, 

You can use wildcard.- in the filename list. Names using wildcards 
wall be expanded into the list of files matching the specification, For 
example, the name :• .has* might yield o .asrr.a in, o , basoxc-r, 
o.bas cmd- 

Usuatty, at least one library file will be specified in the list. A 
library is just a collection of A,OF files stored in a single Acorn 
Library Format file. You can c ,dl the procedures in the library for one 
language from programs written in another, a-s long as both languages 
conform to the ARM E'rocedure Calling Standard and both run-time 
libraries use the common run-time kernel. For example, an assembler 
program CCniid use the C pi: int f function, m long as rhe C nm-rime 
system had been initialised, through the common run-time kernel 

Libraries differ from object iile-s in the way the Linker uses them 
Object files 1 symbols ,ue scanned only once when the Linker attempts 
to resolve external references. Libraries are scanned as many times as 
necessary, It a required symbol ts found in one of the libraries” 
component files, the whole component is incorporated into the output 
file. 

Two common errors, given during a link are caused by unresolved and 
multiple retcrences, ]n the first case, a symbol has been referenced 
from a tile (whose nairn 1 is given in the error), hut there is tw> 
corresponding definition for the symbol This h usually caused by the 
omission of a require i objeer at libntrv file from rhe lint, or rhe mi*- 
spelling of a symbol in rhe original source program. 
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* The second error is caused by a clash of names. For example, a 
procedure might have hem defined with the same name Us u library 
procedure, or a procedure in another object file. 

* The -outpui keyword is obligatory, it is followed by the name of the 
file to which the final linked program should he written. If you jusi 
warn to use Link to check ohjeci files for unresolved references, you can 
specify the device nyl L : as the output tilej the final object code will 
be discarded. The output is usualU in Arthur Image Format, which can 
he executed directly. An alternative format allows low-level 
debugping with Dbijg. 


Simple examples 

Before we move on m describe the rest of the Link command's options, we 
Hive some examples us me the syntax described so far. 

Link -OUTPUT test,sisve aof*sieve, paslib 
Link -o . my basic acf-tas 1 _ ib . f"" 

Link -o noil: aof,comp'' 


VIA KEYWORD 


Sometimes you may want to link a larpe number of tnpui hies which would 
be tedious to type on a command line, and whose name* enn'x conveniently 
be matched by a wildcard specification. To solve thi? problem, you can 
store n list :it input filenames in another file and use the -vis keyword to 
Mivt- rhe Linker acces- to them F'T example, suppose you created the file 
ba w files wLth the contents: 

aof.main 
aof.expr 
aoficrad 
aof,stunt 
aof.lex 
aof.filing 



aof*tokens 


It you then uised the command 

*link -c basic -via fiasfiles lit 

then the file* luted in basfiles would he linked, together with die AOF 
file lib- 

CASE KEYWORD 

[f you specify - case in the command line, then the Linker will not treat the 
case of letter? as significant in identifier*- B'. default, the identifiers main 
and Main refer to different object*, a* they are spelt differently. However, 
with 

-case set, they are the same identifier. 

One reason for using this flag is if you are linking a C object file wirh one 
from a language such as ISO-Pascal or Foumn-77, both of which are case 
insensitive These languages plant symbols in object files in upper case, 
regardless of how they are spelt in the source file* 

RASE KEYWORD 


By default, the base address of the output rile oi the Linker is St&ODO. Thu 
corresponds to the start of application workspace on the Archimedes 
computer, Alternatively, if the - dbug option o given, the bast address is 
set to GlSQOOO. Tins is so thar the debugger program Dhjg can load ar 
St 5000 as a normal application, and load the file to be debugged above 
itself iThere are other changes when ~dbuq is given, as described below.) 

Using the - c ase keyword, you can set the base address of the output tile 
to any desired value For example, you may want a program to have a hi^h 
load address (as with the -db^g option set), hut still be directly 
executable (which a dbug file in AOF format isn't). 
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The keyword is fallowed by a nuother given the base address desired for 
the Otftpui fi le> eg -1 a g & t a 0 0 0 0, - b a s e 2 5 6 k etc. When this is done, 
all relocatable objects in the input files arc relocated using that base 
instead of the default 

VERBOSE KEYWORD 

If you specify -verbose on the command Lne r the Linker gives a report ivj 
ith progress, A message is printed as each file is opened and as each 
module is being relocated. For example: 

link: opening p.basic 

link: opening o,ba3i 

link: opening o,bas2 

link: reiocatino module o.bssl 

link: relocating module o.bas2 

link: relocating module ansilib (fpprintf) 

# # * 

RELOCATABLE KEYWORD 

Usually, when an image file is produced, it will execute correctly only at 
the base address given for the default). This is because the program Wilt 
contain references to absolute addresses within itself. However, if you 
specify the -relocatable option, the final program will be relocatable, 

That is, it can be loaded and executed at any address 

This teat m achieved by adding a relocation ruble and a small program to 
perform the relocation to the image. The relocation table is a List of offers 
from the itart of the program to words which need relocating. These word' 
ire adjusted by the difference between the base address of the program 
and the address where it was loaded. Once ihe relocation has been 
performed, the program proper start* executing. 

Note that although this ibiluy can be used to make s program t&rically 
relocatable, Li does not cvohrm true position-independence on the proKittm- 
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That is, the program Could nor be moved in memory once it has carted and 
»rill hr expected to work- 

DBUG KEYWORD 

It a program is linked using rhe -cibuij byword, an executable Linage is 
not formed, Instead, an AOF file is created which contains all of rhe 
symbols found tn the original source files The code segment nf the file can 
be executed under the control of a Dbug program, acid rhe content* of die 
code and data segments may be examined (and altered in the case of rhe 
dara segment). 

PREDEFINED LINKER SYMBOLS 

There are several symbols which the Linker knows about independently of 
any of its input 'ties. These ■.tart with, the string Inane$$ and, along with 
all other external namrs containing S$. are reserved hy A com. 

The symbols ate 

ROSS Base Address of rhe start of ihe read-only (code) area 

ImageS$R0$.$Limit Address of the byte beyond the end of code area 

ImageSSRWSSBase Address of the 4 tart of rhe readywrire (data) area 

Image'Ssp>‘5$l irut Address of the byte beyond the end nf the data 

area 

Although it will often be rhe case. Acorn dn not guarantee that rhe end of 
ihe read-only urea corresponds to the start of the rcad/wnte area You 
'h.'uld therefore not rely on rha$ being mie 

The rcad/wrTite idata) area may contain code as programs ate somerimes 
srlLfflixlifvmg- >m'il *rly. the read-only (code) area may contain read-only 
dara {eg stfing liimb in C; listing-point constants; etc) 

These symbols can be imported as relocatable .iddreMes by assembly 
language murines that m;jhr need rhem. 


136 




NDEX 


;mem pseudo file 14 

(period) 6 

\ escape character 3? 

Alignment of data type-, 26 
analib library 41 
Appendix A.6., of ANSJ draft "51 
Argument pavung >7 
Argument, fn flag 3! 

Arguments. to mainO 31 
Arithmetic operation-, 28 
Array type* 34 
arr_ prefix 41 

Arthur Symbolic Dcbuuger 15 
ARTHURJ0EWJ4AME3 macro 41 
^rrhurlsh 41 
Arthur!Lb function 
adval () 48 
circled 45 
cirdefillO 4- 
clfiO 43 
cls{) 43 
colour(} 43 
cur*or() 43 
draw(.) 43 
dfflwhyO 43 
fil1{) 43 
gwIO 43 
get( 1 46 
get_bear() 47 
ger_beatsO 47 
ge^rempnf ) 47 
gwindowO 44 
in k ey 0 46 
modeO 44 
Ti(K>useB{) 46 
mnuseXO 46 
mouncYf ) 46 
move{ > 44 


move by {) 44 
orlglnO 44 
osargsf S 48 

osbyicO 48 

osiilet )■ 48 
o?find(J 4fi 
osgbpb() 4° 
rcwardt) 4^ 
palette() 44 
plot{) 44 
point t) 44 
post) 44 
rcct-ingldl 4 ^ 
recfangleftHO 45 

mdO 49 
set_beats{) 47 
$cr_tempoO 47 
sound () 47 
itereoO 47 
stringprintO 45 
swt() 49 
rvi*f 1 49 
rati) 45 
ftnti) 45 
vdu() 46 
v Juq(J46 
vduwf) 46 
voicest) 48 
vpody 46 

arrhurlih libran 41 

ASCII 32 

Assembler listing 16 

B»Us 64 6 

Base. LinkcT keyword I H 

Birfrelds 2? 

Brarii 10 


C-5Librooc environment variable 7 
Calling program?, from. C 105 


117 


Case, Linker keyword JI4 

*cc command 5„ 9 

Character see .32 

Code general ion 15 

Comments, Ln pre processor nurpur t 5 

Compiler options tO 

Compiling 4 propram 9 

Conversions, floating point 29 

Dbug, Linker keyword I L6 
Debugger 15 

Deprecated constructs Id I 
Distribution disc 3 

Ecocict 4 
Environment 31 
ermo 38 

Error messages, non-serious 71 
Error messages, serious SO 
Errors, system l DO 
Escape sequences 33 

File suffixes 6 
Filename conventions 6 
Filename translation 13 
Flag 

-clIJS 
D 16 
-E 15 
-fit* IS 
^15 

4 7* 12, H 
4 7* 12, 15 
4 8, 11 
o8 t 16 

-p 16 

-S 16 
-U 17 
-W ]? 

-r 15 


Flaps 10 
float.h 24 

Floating point emulator 4 
Floating point format 24 
Floating point operations 29 
Function 37 

maps r ore {) 16 
abort i .) 39 
assert0 36 
clockO 40 
fprintff ) 39 
fscanfO 39 
ftel 10 39 
gcrcnvC) 40 _ 
isalnumi) 37 
isalphaO 37 
tscntrlO 3? 
is lower () 37 
isptinlf) 3? 

UpunctO 37 
isupperO 37 
mainO 31 
perrorU 39 
removeO 39 
rename!) 39 
^etimpO 38 
setlocabO 37. 40 
signall) 38 
strcmpO et aE 40 

strerrnri,) 40 
systemO 40, 105 
time{) 40 

Function workspace 59 

h-float 24 
Minors 24 

Header files, in PCC-tnode 103 
Hello W 7 

Identifiers 23 


118 


NDEX 


Identifiers, limit*. 32 
IEEE M | 

Image file H5 

Implementation details 23 
Implementation limit- 10 
Instore tiles 14 
Include file* ?, 12 
Installation 3 
mscallHD 4 
InstallNET 4 
Integer representation 28 
ISO 88 59-1 character set 32 

K&RC n, 101 

Keyword 

-atthuT 10, 41 
-help 10 
-list 7 t 11 
-pec 11, 101 

r SUptT 1 0 

Keywords 10 

Libraries 1 I 
Library 112 
Library files 8 

Library 1 unctions, in PCC-rnoJe 104 
Limits of implementation 30 
Liruta-h 24 
♦link cnmirund Z I 
Linker 111 
Linker keyword 
'base 114 
-case 114 
-dbug 116 
-relocatable 115 
-verbose 115 
-vis 113 

Linker, keywords 111 
Linker options 111 
Linker, output file 16 


Linker, predefined symbols 116 
Linker symbols I 16 
Linking 11 

Macro 

ARTHUR_NEW_NAMES 41 
NULL 27 
Making n backup 4 
MS-DQS 13 

Naming conventions 6 
Non-scnous errors 71 
HULL macro 27 

Object flics 7 

Operating, system coranuti.i. 105 
Options 10 
Options, linker 111 
OS commands 105 

PCC-mode 101 
Pointer arithmetic 2T 
Pointer types 27 
Portable C compiler 11, 101 
Pre-processor 12, 36 
Pre-processor, in PCC-mode 101 
Pre-proccswr output 15 
Pre-processor symbol If, 17 
Procedure call standard 53 
Pnmedure entry 57 
Profiler 16 
Program lilcs 8 

Redirection 31 

Register names 55 

Register usage 56 

Register variables 34 

Relocatable, Linker keyword It 5 

Relocation table 115 

Return from function 58 


Rounding 29 

ftlllllLjIly tUc t-MEil'lldf 9 


Serious erroi* SO 
Shift operations 28 
Siymil() code 

SSGABR1 IB 
SIGFPE 38 
SIGILL 38 
SIGINT sa 
SLGSEtiV 16 
SIGSTAK 18 
SLGTERM 38 
SKiSTAK event 22 
Si;c pi data types 2 3 
Source files 7 
Springboard 10 
Sta..k overflow 60 
Stack overflow chrtkmjt 2_ 
ijtderr, redirection 31 
stJin T redirection 31 
admit. redirection 31 
Storage of data types 23 
struct 35 

Strutr function result* 5.i 

Seme lured ivp-ts, imp It nu nidi tun dtt.ul- 36 

Symbol*. in linker Lib 

Symbntv. predefined Linker symbol* 116 

System esrors I DC' 

System include path 7„ 12 

System library path ’ 


Unary + operatot 30 
union 5 3 

UNIX H 

Usual irithmetic conversittns 29 


\ erf^tsc, Linker keyword 115 
Via, Linker keyword 113 


Warning rue stages 17. 63 

Wimp function 

clase^templateO 53 
dove wiftdO 51 
create, icon!) 5C 
crcate_mcmi() 52 
create, wind!) 50 
decode, me mi (1 52 
delete.icon!) 51 
delete.windO 50 
dtag_boj(0 52 
force, red rawO 52 
gtt„car*E_pQs() 52 
frtt_ii:on_staieO 52 
te t..point. mM i 52 
g et_rec tangle [) 51 
get_witid_jH8icO 51 
IciaJ,templi3te0 53 
open_iemplate( J 53 
open ,wind() 53 
poll_wi.inp() 51 
rcdraw_W'irirfO 51 
set_caiet_pOs0 52 

set.cxteruO 52 

set^ ictin^ state (1 5! 
iet_pomt_shapei) 52 
updiitc_windU 51 
w_mLTjalisei > 50 
which. icoiiU 52 

Workspace, in tun ct ion calls 59 


120 


( ( ' 













* 
























I 












